What VCode tells every agent

Agents: claude, codex · On: phone, desktop

Every agent started in a tab gets the same short instruction block and the same four environment variables. That is what makes the plan strip fill itself and what lets an agent put a screenshot in the transcript.

Why you would use it

It explains behaviour you will otherwise find odd: why the agent keeps a todo list you did not ask for, why it sometimes posts images inline, and why v-code is a command that exists inside a thread and nowhere else.

How to use it

From your seat, nothing. From an agent's seat, inside a thread:

v-code todo add "<step>" for each step, before starting.
v-code todo start <id> when a step begins.
v-code todo done <id> --note "<outcome>" when it finishes.
To show an image: copy it to ~/.v-code-shots/ and write a markdown image line for it on its own line.

What you see

The plan strip above the transcript fills as the agent works, with an outcome note on each finished step. Images the agent posts render inline in the transcript.

The plan strip expanded over the transcript: five steps, two ticked, one running and two still to do, with the summary line above them reading 2/5.

Options and settings

Variable	Value	What it is for
`VCODE_THREAD`	this thread's id	Tells `v-code` which thread it is in
`VCODE_API`	`http://127.0.0.1:<port>/api`	Where `v-code` posts
`VCODE_TOKEN`	the auth token, or empty	Always set; empty means auth is off, absent means not inside a thread
`PATH`	prefixed with the repo's `bin/`	Makes `v-code` a command the agent can type

The three VCODE_* values are set a second time under their names from before the rename, PORTAL_THREAD, PORTAL_API and PORTAL_TOKEN, which a resumed session or an older skill still reads.

The instruction block itself, sent to claude as --append-system-prompt and to codex as developerInstructions on thread/start, says: VCode shows a todo list above the transcript; inside a VCode thread use the v-code todo CLI for any task with more than one step; TodoWrite and TaskCreate feed the same list but cannot carry an outcome, so prefer the CLI; how to post an image (copy it to ~/.v-code-shots/, see the v-code-screenshots skill); and to use Agent subagents for three or more genuinely independent tasks, or a workflow that needs independent reviewers — but not to delegate simple or serial work just to populate the interface.

Limits and known gaps

One string, one file, for both vendors. If the two texts drifted, one vendor would quietly be working off the old instructions.
opencode is given no VCode prompt: it is not started through either of those two channels.
codex gets developerInstructions, not baseInstructions — the latter would replace codex's own prompt outright.
The environment is a copy of the server's. VCODE_THREAD is never written into the server's own environment, or the first thread's id would end up on every agent spawned after it.
PATH is prefixed, not appended, so the bin/ an agent finds is the one belonging to the server it is talking to.
A bind address is not a URL: a wildcard bind is dialled on loopback, and an IPv6 address is bracketed, so v-code can always parse the origin.