Agent CLIs

Vincent orchestrates agent CLIs you install and authenticate yourself. It stores no credentials, embeds no model access, and speaks to no vendor API of its own: an agent step spawns the same binary you would have run by hand, in the task’s worktree, with its prompt on stdin.

Three adapters ship. What an adapter cannot do is documented and ignored at run time — never emulated. A field an adapter has no concept of is stated as ignored here and in the spec, so a workflow never appears to honor something it silently drops.

• At a glance
• Claude Code
• Codex
• Cursor
• How vincent finds a CLI
• Agents in a container
• Choosing models and effort
• Choosing between them

At a glance

vincent agents, the TUI’s daemon view, and GET /v1/agents all report what vincent actually resolved on your machine — path, version, the model and effort options it discovered, and the health verdicts below: whether the build you have is one vincent has been tested against, and whether the adapter can restrict anything on this operating system.

Claude Code

Binary: claude. Workflow value: agent: claude.

The most capable adapter, and the only one that can be interrupted mid-step.

• Runs claude -p --output-format stream-json --verbose, cwd set to the worktree, prompt on stdin — never as an argv element, because Windows caps arguments at 8 KB and prompts embed task descriptions.
• full-auto adds --dangerously-skip-permissions; restricted maps to Claude’s allowlist flags with an edit/read/git/test tool set — plus mcp__vincent__* in full, so restricted bounds the filesystem and the shell, not what the step does to vincent. See Driving vincent from an agent.
• Resumes its own session, with --resume <session_id>. That is what makes a chat work: vincent stores the session_id claude stamps on its stream and hands it back on the next turn, so turn N sees turns 1..N-1 without anything being replayed into the prompt. Workflow steps never set it — every step still gets a fresh session. A session the CLI no longer knows fails that turn with session_lost rather than quietly starting a new one.
• Carries vincent’s own MCP server on --mcp-config with an inline config, alongside --strict-mcp-config so your own MCP servers never leak into a step. Per run: nothing global is written.
• model: and effort: pass straight through as --model / --effort. Options are discovered by parsing claude --help and merged with a curated catalog, so a CLI upgrade that adds an effort level makes it selectable without a vincent release.
• Reports the most about its own run. The output pane’s # header line — the working directory and the tool set a run was given — and the closing line’s duration, turn count, cache-token split, per-model breakdown, refused tool calls and stop reason all come from claude’s stream and from no other adapter’s. A tool call a permission rule refused is marked apart from one that ran and failed. See the output pane.
• Reports its subagents. When claude hands work to subagents, every line names the one that produced it, and claude says how each one ended. The output pane and vincent task transcript draw that work nested behind a rail rather than as the agent’s own. Codex and cursor report no subagents, and vincent does not infer one from their tool calls. See When the agent runs subagents.
• Reports what its edits changed. An edit’s outcome is the lines it added and removed, ✓ +13 −9, and at verbose the output pane shows the hunks themselves. A new file reads created, and a subagent’s edits keep claude’s own sentence, because claude reports no change for either. Cursor reports the counts for its edits and no hunks; codex reports neither. See the output pane.
• Reports token usage and cost. The board’s cost column sums every attempt, retries included. The other two adapters report no cost at all — which also means max_task_cost_usd can only stop a task that ran on claude. The same goes for max_tree_cost_usd: a fan-out tree counts only its claude spend, so codex and cursor lanes add nothing to the total.
• Recognizes a spent usage quota and a logged-out CLI in the output of a run that failed. A quota stop becomes usage_limit — no retry consumed, and by default the task waits and re-runs itself, though usage_limit_auto_continue can make it block for you instead — and a logged-out CLI becomes agent_unauthenticated, which blocks with the fix named. Codex and cursor do neither: their wordings have not been captured from a real run (doing so means burning a real quota window), and vincent will not guess at one, because a wrong guess parks a genuinely failed task in a wait it never leaves. On those two, both conditions still read as agent_error or nonzero_exit. See Troubleshooting.
• Reports its remaining quota, but only by pushing. There is no usage subcommand to poll; what Claude Code has is a status line, which it hands both usage windows on every render. vincent statusline is what catches them, and the daemon view’s i is what installs it — after showing the exact JSON it would write to ~/.claude/settings.json. Until then claude reports nothing, and a claude step in a container reports nothing either. See How much quota is left.

Mid-run questions

Claude Code is the one adapter with a control channel, so a step can pause, ask, and resume in the same session. When the agent uses its AskUserQuestion tool, vincent normalizes the request into a question (with option labels, and multi-select honored); in restricted mode a denied tool surfaces as a permission request instead.

The task moves to awaiting_input, keeps its concurrency slot, and pauses the step’s timeout clock. Answer from the TUI popup or POST /v1/tasks/{id}/answer; the run resumes where it stopped. Set on_input: deny on a workflow that must stay unattended — see Writing workflows → mid-run questions.

Input support is version-gated to the CLI family vincent has verified against real captured runs. Outside that range the adapter reports supports_input: false and runs exactly as it otherwise would — no input flags, plain-text prompt. Nothing degrades silently.

A workflow that needs the conversation says on_input: require, and then a claude outside the verified family is refused for that step rather than run unattended — GET /v1/agents reports input_verdict: "unsupported" for it, and a step that reaches the engine anyway fails with input_unsupported.

Codex

Binary: codex. Workflow value: agent: codex.

• Runs codex exec --json, cwd set to the worktree, prompt piped on stdin.
• full-auto maps to --dangerously-bypass-approvals-and-sandbox — the documented automation switch. restricted maps to --sandbox workspace-write, confining writes to the worktree.
• model: passes as -m; effort: as -c model_reasoning_effort=…. Efforts are minimal, low, medium, high, xhigh.
• Carries vincent’s own MCP server the same way: -c mcp_servers.vincent.… dotted overrides, with the bearer token handed to the child in its environment rather than written down. Per run — your config.toml is never modified.
• No model catalog. The CLI enumerates nothing, and codex model availability is account-dependent — the same id is accepted on one plan and rejected on another — so pickers offer free text and the CLI’s own default. A model you type is passed through with a warning, not rejected.
• No cost reporting, and supports_input: false: a codex step never enters awaiting_input, and on_input: wait|deny has no effect on it. on_input: require is the one that does: a step declaring it cannot use codex at all, and a workflow pinning agent: codex on such a step fails validation.
• Resumes its own session, so codex holds a chat like Claude Code does. Resume is a subcommand rather than a flag — codex exec --json resume <thread_id> — and the prompt stays on stdin, because exec resume reads stdin when it is given no prompt argument. vincent stores the thread_id the stream reports on thread.started and hands it back on the next turn. The argv is pinned by a capture against codex-cli 0.150.1; nothing is emulated, and vincent never replays a conversation into the prompt. Workflow steps never set it: every step still gets a fresh session. Two consequences, both stated rather than worked around:
  • A resumed run is always full-auto. codex exec resume has no --sandbox, so restricted has no spelling on it. Only a chat turn ever resumes, and a chat you start yourself is always full-auto — there is no permission mode to ask for on one. A chat opened on a task is the exception: it takes the task’s permission mode, and codex cannot keep a resumed turn restricted. So opening a codex chat on a task that runs restricted is refused, and codex itself refuses a resumed restricted run rather than running it full-auto. claude and cursor pass their restriction on every turn, so use one of those for a chat on a restricted task.
  • A thread codex no longer knows fails that turn with session_lost rather than quietly starting a new one.
• The plan and command output are surfaced. Codex reports a running to-do list, which the pane shows with a ☰ gutter at the normal and verbose output levels, ticking over as the agent works. What a command printed shows at verbose only — it is the output body, and a step running go test ./... would otherwise flood the level most readers use; a body long enough to hit the cap ends in … output truncated. File changes are named by their paths and kinds, and MCP calls by server and tool.
• Token usage is read whole. All five of the counters codex reports land in the run’s accounting, so verbose shows a codex turn’s cache read/write split and its reasoning spend rather than leaving them blank. Cost is still absent, because the CLI does not report one — see the bullet above.
• Reports its remaining quota on request, and is the only adapter that needs no setup to do it: codex app-server --stdio answers account/rateLimits/read with its primary and secondary windows, which vincent asks for on the ordinary catalog refresh. A missing binary, a logged-out account, a timeout or a malformed answer degrade silently and fail no probe. See How much quota is left.
• Reasoning is surfaced. Codex emits whole reasoning blocks, which the TUI shows at the normal and verbose output levels (v cycles them) and the transcript records as agent.thinking. Whether any are emitted depends on the effort you asked for — a low-effort turn can spend reasoning tokens and produce no blocks at all.

Caveat on restricted + git. In a linked worktree the real git directory lives under the main repository, outside the sandbox, so a git commit from a restricted codex step may be denied. Vincent itself never needs a commit — the diff reads the working tree — but a workflow that commits from a restricted codex step should use a command step for the commit instead.

Cursor

Binary: cursor-agent — never cursor, which is the editor launcher and would open a GUI. Workflow value: agent: cursor.

• Runs cursor-agent -p --output-format stream-json --trust, cwd set to the worktree, prompt on stdin. full-auto adds --force; restricted adds --sandbox enabled instead.
• --trust is passed in both modes: a task runs in a git worktree the CLI has never seen, and a workspace-trust prompt in a headless run is a hang, not a question.
• Vincent’s own worktree flags are never passed to it. Cursor has a worktree feature; worktrees belong to vincent, and two owners of one concept is a defect.
• Reports token usage but no cost, and supports_input: false — so, like codex, cursor cannot back a step declaring on_input: require, and pinning it on one is a validation error.
• Resumes its own session too, with --resume <session_id> — the same session_id its stream stamps on every line — so cursor can hold a chat. Unlike claude and codex it has no way to tell you a session is gone: handed a --resume id it has never seen it starts a fresh chat under that id and answers normally, so a cursor chat whose session has aged out replies without remembering the conversation instead of failing session_lost.
• Errors do not arrive in the stream — an invalid model id exits 1 with a message on stderr and no result line — so the adapter reports “stream ended without a result event” plus the stderr tail, which is what makes an everyday typo diagnosable.

Four things about cursor are genuinely different, and all four are visible in a workflow:

1. Effort lives in the model id

Cursor has no effort flag. Reasoning depth is encoded in the model: claude-sonnet-5-thinking-xhigh, gpt-5.4-mini-high. So effort: on a cursor step is ignored, its effort catalog is empty, and vincent workflow validate rejects a claude or codex effort value on a cursor step — which is exactly the error a workflow author needs to see.

Run cursor-agent models to see what your account offers; vincent probes the same list.

2. A cursor step overwrites your saved CLI model

Cursor persists whatever --model it is given into ~/.cursor/cli-config.json, so leaving the model unset means “whatever the last invocation chose” — possibly a previous vincent step. To keep runs reproducible the adapter always passes --model, defaulting to auto.

The accepted cost: running a cursor step overwrites the model you last picked in an interactive cursor-agent session. Determinism is worth more to an orchestrator than preserving an interactive preference, and auto at least lands on cursor’s own default rather than on wherever the last task left it.

3. restricted needs macOS or Linux

--sandbox enabled exits 1 on Windows with “Sandbox requires macOS or Linux” before doing any work. Vincent therefore refuses to create a task whose restricted step resolves to cursor on Windows: POST /v1/tasks answers 400 naming the step and the agent, and the TUI shows that message on the new-task form. A task that reaches the engine anyway — a data directory carried to Windows, or a workflow edited after the task was queued — fails to start with block reason restricted_unsupported, under the normal retry policy.

Falling back to --force was rejected outright: it would run full-auto a step that explicitly asked not to be, turning a safety choice into its opposite on exactly one OS — the failure mode nobody would think to check for. See Windows.

4. A cursor step writes .cursor/mcp.json into the worktree

Cursor has no per-run MCP flag at all — cursor-agent mcp reads only .cursor/mcp.json in the workspace or ~/.cursor/mcp.json globally. So to give a step vincent’s own tools the adapter writes the workspace file into the task worktree before the run, passes --approve-mcps so a headless run does not stop on a trust prompt for the server vincent just configured, and removes the file (and an empty .cursor/) after the step ends. Your global ~/.cursor/mcp.json is never touched.

The accepted cost, and the one you can see: while a cursor step is running, that file is an untracked file inside a git worktree. It shows up in git status, in the task’s diff, and in dirty detection for the duration of the run. It is gone once the step ends, and if the daemon dies mid-step recovery sweeps it on the next start. The alternative — writing your global config instead — was rejected: a per-task change to a file you own outside vincent is worse than a transient file inside a worktree vincent already owns.

mcp.wire_steps: false skips all of it: no file is written and --approve-mcps is not passed.

The model list is advisory in both directions

cursor-agent models lists roughly 180 ids, but the list is account-scoped and still over-broad: an id it lists can be rejected at run time. So membership is a hint, free text stays accepted, and the CLI is the final authority. The TUI’s model picker is windowed and type-filterable for exactly this catalog.

How vincent finds a CLI

By default the daemon resolves each adapter’s binary from PATH. Override it per adapter in config.yaml:

agents:
  claude: { path: "" }                              # "" = resolve from PATH
  codex:  { path: "/usr/local/bin/codex" }
  cursor: { path: "C:/Users/me/.local/bin/cursor-agent.exe" }

An explicit path is absolute and never consults PATH, which makes it the standing fix for “my shell finds it, vincent does not”.

Detection is cached by binary identity — resolved path + mtime + version. Help output is a pure function of the installed binary, so the cache cannot go stale by construction: upgrading a CLI invalidates it and the next request re-probes. vincent agents --refresh, GET /v1/agents?refresh=true or R in the TUI’s new-task view forces one.

A failed probe expires; a clean one does not. Nothing about a binary changes when a probe times out, so caching that failure forever would serve one bad moment for the daemon’s whole lifetime.

Probe failure degrades rather than blocks: if a CLI is missing or its help output cannot be parsed, vincent serves the curated catalog with probe_error set, and free-text entry is unaffected.

“Found” is not “usable”

An installed but unauthenticated CLI probes as healthy and then fails every single run. Every supported CLI can answer that cheaply, so vincent asks: claude auth status, codex login status and cursor-agent status populate logged_in with a definite true/false. claude is asked only from 2.1.41, the build that introduced auth status, up to 3.0.0; an older (or not yet verified newer) claude is never asked, reports null, and the TUI renders that as unknown rather than as fine.

true means the CLI found credentials configured, not that they work: a claude.ai login, an ANTHROPIC_API_KEY or a Bedrock/Vertex switch all report true for claude, and codex’s login status makes the same claim. An expired or revoked key still shows up as a failed step. vincent reads only the yes/no — never the account email, organization or plan the CLI prints alongside it.

No probe ever guesses. For codex and cursor, a non-zero exit is false, an explicit negative is false, an explicit positive is true. For claude, only the loggedIn field of its JSON answer decides, whatever the exit code — a bare exit 1 is just as often a CLI error. And for all three, anything else — including a probe that times out or cannot be spawned — is null. That last rule is why a slow machine never gets told it is logged out: on Windows a killed probe exits 1, and reading that as “not authenticated” would be a false accusation.

vincent doctor prints this row for every adapter and re-probes each time, so logging in and running it again shows the change immediately — unlike GET /v1/agents, which serves the binary-identity cache.

If a service-installed daemon reports agents as missing while the same daemon started by hand finds them, that is a PATH capture problem — see Running at login.

logged_in gets its own five-minute freshness window inside that cache. Binary identity is exact for --help output and only a floor for auth state — nothing about the binary changes when you log in — so past five minutes vincent re-asks that one question and leaves the option catalog alone. A re-ask that fails keeps the previous answer rather than downgrading it, for the same reason the probe never guesses.

Was this build ever tested?

Every adapter carries the list of CLI builds vincent’s parsers were captured against, and reports a verdict on the one you have installed:

untested is the normal, expected answer. Agent CLIs ship far more often than vincent does, so a few weeks after any release most people are on a build newer than the fixtures — and it is expected to work. The verdict is advisory everywhere: no run is refused, no task is blocked, and vincent doctor does not exit 1 over it. It exists so that when something does look wrong, you can tell at a glance whether you are on ground vincent has walked.

Comparison is exact: cursor’s version is 2026.08.04-aaa8809, calver plus a commit sha, which no version range can order — so rather than have one adapter answer a different question from the other two, all three compare whole strings. The incompatible list ships empty for all three, because no such build has been observed.

vincent doctor and the TUI’s daemon view print the verdict beside each adapter, along with the builds it was judged against; GET /v1/agents carries it as version_verdict and tested_versions.

Can this agent restrict anything here?

restricted_verdict answers whether an adapter can honour permission_mode: restricted on this machine. Cursor answers unsupported on Windows and supported everywhere else; claude and codex answer supported everywhere.

This is the one health verdict that refuses something. A task whose restricted step resolves to an adapter that cannot restrict here is rejected at creation with a 400 naming the step and the agent, rather than being allowed to spend a worktree and a retry to fail with restricted_unsupported. The answer does not depend on the installed binary — it is a fact about the adapter and the operating system — so it is correct even where the CLI is missing entirely.

The step failure still exists as a backstop, for a task whose daemon changed underneath it: a data directory carried to Windows, or a workflow edited after the task was queued.

How much quota is left, and who will say

Two of the three adapters can now answer “how much quota do I have?” without running a step, and they answer in opposite directions.

• codex answers on request. codex app-server --stdio speaks JSON-RPC over stdio and replies to account/rateLimits/read with the same primary and secondary windows the CLI prints when it walls a run. Vincent asks on the ordinary catalog refresh — at most once every five minutes, and unconditionally on vincent doctor, vincent agents --refresh or GET /v1/agents?refresh=true. There is nothing to install and nothing to configure.
• claude pushes. Claude Code has no usage or limits command to poll, but it hands its status line a JSON object carrying both windows on every render. vincent statusline reads that object, posts it to the daemon and prints the status line you already had; the daemon view’s i is what installs it, after showing the exact JSON it would write to ~/.claude/settings.json. Nothing is reported while it is not installed.
• cursor cannot. cursor-agent about --format json reports a plan tier and no numbers, so cursor implements no quota capability at all, spawns nothing, and is observation-only exactly as before. Vincent does not emulate what an adapter cannot do — there is no “cannot report” stub and no fabricated percentage.

A reported reading is held in memory, not the database: it is as durable as the daemon, and a restart drops it until the next probe or push. Nothing here can fail a probe — a missing CLI, a logged-out account, a handshake that times out or a malformed answer all fall back to the behaviour below, and probe_error keeps meaning only “the option probe failed”.

Underneath both, vincent still remembers. When an agent stops on a spent window, the daemon records that per adapter — when it was seen, when it resets, and whether the CLI named that reset or vincent estimated it from usage_limit_recheck_interval. That observation outlives the task’s own wait, and is what an adapter with no reported reading is rendered from. A reading wins where there is one, so:

• the board header badges the adapter — claude ⏳14:20 instead of claude ✓;
• the daemon view spells it out beside path, version and login state. A reading is written window by window with the time it was taken — quota codex app-server · 5h 28% → 13:00 · 7d 53% → 11:00 · read 09:14 — and an observation as usage limit → 14:20 with → for a reset the CLI stated and ≈ for one vincent estimated. An adapter with neither says quota unknown;
• the new-task form warns under the agent row — · usage limit until 14:20;
• vincent agents prints the same block in its QUOTA column for a shell or a script, with full local timestamps because a seven-day reset is days away — codex app-server · 5h 28% → 2026-09-16T13:00:00+02:00 · … · read …, spent → … or spent ≈ … for an observation, unknown for neither.

The warning is advisory. The form still submits and admission is unchanged. A task queued against a window vincent watched close parks on the ordinary usage_limit wait when it reaches its agent step, without starting the agent. If usage_limit_auto_continue says not to wait, it starts and finds the limit itself. A reported reading never holds a task, even at 100%. Since only claude recognizes a quota stop at all, that key is inert on the other two, exactly as the table above says. The next successful step on that adapter retires the observation — and only the observation, since a step completing proves the wall vincent watched has come down and proves nothing about a percentage a vendor reported — so an estimate is never left standing over a CLI that is visibly working.

GET /v1/agents and GET /v1/info carry all of it as quota, whose source says which kind of fact you are holding.

Agents in a container

Set container.image and a task’s agent steps run inside the task’s container, next to its command steps. The CLI that runs is the image’s, not yours: vincent looks up claude, codex or cursor-agent by name on the image’s PATH. agents.*.path is a host path and is ignored there, and the host does not need the CLI installed. An image without it fails the step agent_unavailable. The transcript, the token and cost records and the exit code are the same as a host run’s. Chats are not tasks and run on the host — except a chat opened on a containerized task, whose turns run in that task’s container with the image’s CLI, resuming the session the mounted agent configuration keeps between turns.

Everything on this page that vincent probes still describes the host’s CLI — vincent agents, vincent doctor, GET /v1/agents, the model and effort catalog, login state, codex’s quota reading and the usage-limit holds. The one exception is claude’s mid-run questions: whether a containerized claude can take an answer is decided by running claude --version in the image, so on_input: require is judged against the claude that will actually run.

Logging in. mount_agent_config, on by default, mounts your ~/.claude, ~/.codex and ~/.cursor read-write under the container’s HOME, so a CLI you are logged in to on the host is logged in inside the container too. There is one gap: claude on macOS keeps its login in the Keychain, not in ~/.claude, and the container cannot reach it. On a Mac, pass CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to the container through environment. Codex’s auth.json, and claude’s own credentials file on Linux, carry over as they are.

vincent status does not work inside a container. The image has no vincent binary, and 127.0.0.1 inside the container is not your daemon. A containerized agent reports what it is doing through the step_status tool on its MCP endpoint instead, which it has as long as mcp.wire_steps is on. If a prompt asks for vincent status, ask for that tool when the workflow runs in a container.

The vincent statusline hook does not report from a container. If you installed it, the mounted ~/.claude/settings.json points claude at a vincent binary on your host that the container does not have. Claude tolerates a status line that fails, so the run is unaffected, but the usage windows it would have pushed during that run never reach the daemon.

Permission modes are unchanged. restricted in a container is still restricted, and full-auto is still full-auto, with the container’s reach instead of your machine’s. Cursor’s “restricted needs macOS or Linux” rule is judged against the host, and a Windows daemon refuses containerized tasks anyway. See the security model.

Choosing models and effort

Set agent, model and effort on a step, in workflow defaults, or per task at creation. Resolution is first-hit-wins:

1. the explicit step field
2. the task-level override chosen at creation (--agent / --model / --effort)
3. workflow defaults
4. the adapter’s default (usually empty — the CLI decides)

Model and effort only inherit from a level whose agent matches. When a step or a task override switches agent without setting them, they reset to the new adapter’s default rather than leaking across — a claude alias like sonnet must never reach codex. The TUI’s new-task form shows which level won for each field, and POST /v1/resolve answers the same question for a script.

vincent workflow validate catches a value belonging to another adapter’s catalog. It cannot catch a model your account lacks: the CLI is the final authority there, and you find out at run time.

Choosing between them

• Anything where you may want to answer a question mid-run — claude. It is the only adapter that can be asked something mid-run; all three can be resumed, so all three can hold a chat.
• Cost tracking matters — claude. The other two report none, so the board’s cost column stays empty for them and a configured spend cap, per task or per tree, never counts their runs. Vincent will not estimate money from token counts.
• Cheap, strictly unattended passes — codex or cursor are fine; set on_input: deny and neither will ever try to stop for you anyway.
• You want a specific model cursor offers — cursor, remembering that the reasoning level is part of the model id and that the step will rewrite your saved CLI selection.
• Mixed workflows are normal. Set agent: per step: implement with one, review with another. A second opinion from a different vendor on the same diff is one of the better uses of a multi-step workflow.

See also

• Writing workflows — where agent:, model: and effort: go.
• Security model — what full-auto and restricted actually mean.
• Troubleshooting.
• Spec §9 — the normative adapter contract.