Skip to content

exec-mode.md

Latest commit

 

History

History
95 lines (66 loc) · 5.59 KB

exec-mode.md

File metadata and controls

95 lines (66 loc) · 5.59 KB

Exec Mode Automation

VT Code's exec mode lets you run autonomous tasks from the shell without starting the interactive TUI. The workflow mirrors the codex exec guidance: commands run non-interactively, stream structured events, and can be resumed later. By default, vtcode exec prints progress, summaries, and outcomes to stderr. stdout remains silent unless you request structured output (via --json), allowing you to safely pipe the output to other tools without pollution.

For the complete runtime lifecycle mapping, see Agent Loop Contract.

vtcode schedule uses this same exec runtime for durable prompt tasks. When a durable scheduled prompt fires, VT Code launches a fresh vtcode exec run in the configured workspace and records the resulting status and artifacts. For session-scoped /loop polling and reminders, see Scheduled Tasks.

Launching exec mode

vtcode exec "count the total number of lines of code in this project"

Exec mode enforces the same workspace trust checks as the interactive UI. The workspace must be marked as full_auto, and the configured automation.full_auto section must enable autonomous execution. When the command starts it automatically activates the full-auto tool allow list and assumes no human is present to grant additional approvals. The agent will not prompt for user input allowances or confirmation dialogs, so ensure the allow list covers every tool it may need. You can capture the final summary separately with --last-message-file or persist the raw JSON stream with --events. Use --json when you want to see the live JSONL feed on stdout.

Dry-run mode

Use --dry-run to force read-only execution while still allowing the agent to analyze and plan:

vtcode exec --dry-run "identify required code changes for adding OAuth refresh token support"

In dry-run mode, VT Code enables plan/read-only enforcement for tool calls. Mutating operations are blocked, and the run reports what would be changed rather than applying edits.

Continuation and verification

Exec mode now uses a harness-managed continuation loop instead of accepting the first completion-sounding assistant message.

  • By default, agent.harness.continuation_policy = "all" enables harness continuation in both interactive and exec/full-auto runs.
  • Review mode and vtcode exec --dry-run stay single-pass and read-only.
  • Set agent.harness.continuation_policy = "exec_only" if you want interactive TUI sessions to keep manual turn control.

When a run starts, VT Code uses task_tracker state as the completion contract. If the model has not created a tracker yet, exec mode creates an internal three-step scaffold (analyze, change, verify) and persists it through the existing task-tracker files under .vtcode/.

Completion is accepted only when:

  • all tracker steps are completed
  • every step-level verify command has passed

Verification commands run sequentially from the workspace root through the existing exec/sandbox stack. The first non-zero exit stops verification, records a harness event, and forces a fresh continuation turn with the failure summary.

Structured event stream

Use vtcode exec --json to emit JSON Lines that match the non-interactive Codex schema:

  • thread.started – emitted once per session with a stable thread_id.
  • thread.completed – emitted once per session with terminal subtype, usage, stop reason, and optional total_cost_usd.
  • thread.compact_boundary – emitted when VT Code compacts history locally or through a provider compaction path.
  • turn.started / turn.completed – wrap each autonomous turn and include token usage on completion.
  • turn.failed – surfaces limit breaches or early exits together with the outcome description.
  • item.started / item.updated / item.completed – track the lifecycle of individual operations.

Supported item payloads:

  • agent_message – final or intermediate assistant responses.
  • reasoning – streamed model thoughts captured from providers that expose them.
  • command_execution – shell or tool invocations with status, aggregated_output, and exit_code fields.
  • file_change – applied patches grouped by path and change type.
  • mcp_tool_call – Model Context Protocol tool runs with tool name, arguments, and status.
  • web_search – provider search calls including the query and optional summary.
  • harness – continuation and verification lifecycle items such as continuation_started, verification_started, and verification_failed.

These events align with the published Codex non-interactive schema so downstream automation, dashboards, or log shippers can reuse existing parsers without modification.

If --events is not provided, exec mode also respects agent.harness.event_log_path. Relative or absolute file paths write JSONL events directly; directory paths get a timestamped harness-<session>-<timestamp>.jsonl file.

agent.harness.max_budget_usd applies to exec mode as well as interactive runs. If model pricing metadata is unavailable, VT Code leaves total_cost_usd unset and skips budget enforcement for that session.

Resuming sessions

Exec runs are resumable via vtcode exec resume <SESSION_ID> <PROMPT> or vtcode exec resume --last <PROMPT>.

vtcode exec resume --last "continue from the prior investigation and summarize the root cause"

Resume uses the archived workspace recorded in the original exec session. The follow-up prompt starts a new autonomous turn on the same archived session identifier, so structured history and the saved session archive stay in sync.