Command Reference

August 7, 2026 · View on GitHub

This guide summarizes common actions and how to invoke them with vtcode. The agent exposes a suite of tools to the LLM; you interact with them via chat. When you ask to search, read, or edit files, the agent chooses an appropriate tool.

Use exec_command.cmd with rg or grep for flexible shell text search.

The default model-visible tools are exec_command, write_stdin, and apply_patch. code_search is available through the advanced VT Code profile. It accepts a required literal query plus optional path, file_types, result_types, and max_results. Its four result categories are recognised definitions, exact syntactic usages, literal text, and matching paths. A usage is a same-spelling syntax occurrence, not a resolved reference. Queries use literal smart-case. When truncated is true, narrow a filter in another call; the response does not claim an exact repository-wide total.

Use exec_command or the specialised ast-grep skill for arbitrary structural patterns.

Examples

  • Find TODO/FIXME with 2 lines of context in Rust files only:
Ask: Search for TODO or FIXME across the repo with 2 lines of context in Rust files.
{
  "cmd": "rg -n -C 2 'TODO|FIXME' -g '*.rs' ."
}
  • Literal search for unsafe { anywhere (hidden files ignored):
{
  "cmd": "rg -n -C 1 -F 'unsafe {' ."
}
  • Search JavaScript files for a function name, case-insensitive:
{
  "cmd": "rg -n -i 'doSomethingImportant' -g '*.js' ."
}

File operations

  • Inspect files with shell commands through exec_command.cmd, such as rg --files, sed -n, cat, head, and tail.
  • Edit files with apply_patch.
  • Continue live shell sessions with write_stdin.

Session resume and forks

VT Code can reopen archived sessions, continue the latest one, or fork a previous session into a new archive.

Resume the latest or a specific session

vtcode --continue
vtcode --resume session-123
vtcode --resume          # interactive picker

Fork from an archived session

vtcode --fork-session session-123
vtcode --fork-session session-123 --session-id bugfix-branch
vtcode --resume session-123 --session-id bugfix-branch
vtcode --continue --session-id followup-branch

Notes:

  • --session-id turns --resume ... or --continue into a fork instead of an in-place resume.
  • --resume with no ID plus --session-id ... opens the interactive picker and then forks the selected session.
  • --all expands the picker/search scope across workspaces for resume and fork flows.

Start a summarized fork

vtcode --fork-session session-123 --summarize
vtcode --resume session-123 --session-id handoff --summarize
vtcode --resume --session-id handoff --summarize   # interactive picker, summarized fork

Summarized forks do not copy the full transcript. VT Code starts the child session from:

  • one structured conversation summary
  • retained recent real user messages
  • the session memory envelope

Normal forks keep the full archived transcript unchanged.

Quick Actions in Chat Input

VT Code provides several quick actions directly in the chat input for faster workflow:

  • File Picker (@) — Type @ anywhere in your input to open the file picker and select files to reference in your message. This allows you to quickly mention files without typing full paths.
  • Slash Commands (/) — Type / at the start of input to access all available slash commands including /files, /stats, and many more.

/code-ide (VS Code integration)

Use the /code-ide slash command to trigger IDE-specific actions from within a VT Code chat session or the integrated terminal. When the VS Code extension is installed:

  • Run /code-ide in the VT Code terminal session to synchronize with the sidebar views and refresh context-aware data.
  • Use the VT Code: Send /code-ide Slash Command command palette entry or the Quick Actions panel to dispatch the slash command directly to the active VT Code terminal.
  • The command will emit IDE events back to the extension host, keeping the Agent Loop timeline, status indicators, and MCP configuration summaries in sync.

Configure the behaviour under Settings › Extensions › VT Code:

  • vtcode.terminal.autoRunChat — Automatically run vtcode chat when the managed terminal opens.
  • vtcode.terminal.allowMultipleInstances — Opt-in to creating new terminal sessions instead of reusing the shared VT Code terminal.
  • vtcode.agentTimeline.refreshDebounceMs — Control how quickly the Agent Loop timeline reacts to incoming terminal output.

Slash-command notes

  • Slash commands are skill-backed. Each command routes through a namespaced command skill such as cmd-status or cmd-review.
  • The /name form remains the compatibility alias. You can also inspect or execute the same behavior through /skills info cmd-name and /skills use cmd-name ....
  • Prompt-oriented slash commands such as /review, /analyze, and /command are shipped as bundled system skills in the release binary.
  • To keep the default prompt lean, command skills are not injected into the runtime ## Skills prompt section; use slash completion or /skills discovery when you need them.
  • /resume opens archived sessions when the current run is idle.
  • /fork opens the session picker and then lets you choose between a full-copy fork and a summarized fork.
  • /compact manually compacts the current conversation context immediately. Use /compact edit-prompt or /compact reset-prompt to manage the saved default prompt for manual compaction requests. On the local fallback path, VT Code keeps a structured summary plus retained user prompts instead of a mixed recent tail.
  • /agent and /agents inspect agent definitions and delegated child runs. @agent-name remains a delegated child-agent control. Primary agents are switched from the TUI with Tab on an empty idle composer. The active primary agent is shown in the session header badge and influences the session's instructions, model, granular permission policy, and tool access.
  • /agents list shows all agent definitions with their availability (mode: primary, mode: subagent, or mode: all). /agents create scaffolds a new agent definition in .vtcode/agents/.
  • /plan starts or continues the planning workflow. It is a workflow command, not a state selector. Execution agents may also suggest it for demanding or multi-phase tasks; interactive policies confirm the suggestion, while full-auto and skip-confirmations policies accept it automatically. When the plan agent needs a material clarification, the inline interview wizard presents selectable answers and resumes planning with the chosen answer. Use /plan off to cancel an active planning workflow without implementing its draft.
  • /checkup runs configuration diagnostics and suggests reversible optimizations. Use /checkup [--quick|--full] (defaults to a full pass); optimizations are confirmed via the selection modal before any config is mutated.

Scheduled tasks

Use vtcode schedule when the task should survive restarts.

vtcode schedule create --prompt "check the deployment" --every 10m
vtcode schedule create --prompt "review the nightly build" --cron "0 9 * * 1-5"
vtcode schedule create --reminder "push the release branch" --at "15:00"
vtcode schedule list
vtcode schedule delete 1a2b3c4d
vtcode schedule serve

See Scheduled Tasks for session reminders, durable daemon behavior, and service installation details.

stats (session metrics)

Display current configuration, available tools, and live performance metrics for the running session. Use --format to choose text, json, or html output and --detailed to list each tool.

schema (runtime tool introspection)

Inspect VT Code's built-in tool schemas at runtime so automation can discover exact tool names and input parameters without relying on stale docs.

Usage

# Full JSON document (default)
vtcode schema tools

# Compact schema descriptions for tighter context windows
vtcode schema tools --mode minimal

# NDJSON output for streaming parsers
vtcode schema tools --format ndjson

# Filter to specific tools
vtcode schema tools --name exec_command --name apply_patch

Options

  • --mode — minimal, progressive (default), or full
  • --format — json (default) or ndjson
  • --name — repeatable exact tool-name filter

update (binary updates)

Check for and install binary updates of VT Code from GitHub Releases. Updates are downloaded and verified against checksums for security.

Usage

# Check for available updates without installing
vtcode update --check

# Check for updates (same as above, default behavior)
vtcode update

Options

  • --check — Check for updates and display release notes without installing
  • --force — Force update even if already on the latest version

How it works

  1. The command checks the GitHub API for the latest VT Code release
  2. It compares the remote version with your current version
  3. If a new version is available, it shows release notes and download information
  4. Interactive TUI sessions automatically check for updates on launch (short cached interval)
  5. Managed installs (Homebrew/cargo/npm) show package-manager-specific update guidance

Standalone releases download the exact platform archive, verify a published SHA-256 checksum when available, safely extract vtcode/vtcode.exe, and replace the running binary natively. Binaries built with the former updater must be bootstrapped once with the native installer before this replacement flow can update them.

Examples

  • Check for updates:

    vtcode update --check

  • Check for updates and show if you're on the latest version:

    vtcode update

dependencies

Manage optional VT Code dependencies such as ripgrep and ast-grep.

Usage

# Install both optional search tools in one step
vtcode dependencies install search-tools

# Check whether VT Code can resolve the optional search tools
vtcode dependencies status search-tools

# Install ripgrep using a supported system installer
vtcode dependencies install ripgrep

# Install the managed ast-grep binary into ~/.vtcode/bin
vtcode dependencies install ast-grep

# Materialize the bundled ast-grep scaffold in the current workspace
vtcode init

# Run ast-grep rule tests and scan for the current workspace
vtcode check ast-grep

# Check whether VT Code can resolve ast-grep
vtcode dependencies status ast-grep

Notes

  • vtcode deps ... is a short alias for vtcode dependencies ...
  • vtcode dependencies install search-tools bundles the recommended ripgrep + ast-grep setup after any install method
  • vtcode dependencies install ripgrep installs rg through a supported system installer and keeps startup non-blocking when you skip it
  • vtcode init materializes VT Code's bundled ast-grep starter files into the current workspace: sgconfig.yml, rules/, and rule-tests/
  • vtcode check ast-grep is the first-class replacement for the repo-only ./scripts/check.sh ast-grep flow
  • VT Code does not auto-edit your shell profile; add export PATH="$HOME/.vtcode/bin:$PATH" yourself if you want the managed binary outside VT Code
  • On Linux, prefer ast-grep over sg
  • The curl installer includes the search-tools bundle by default; use --without-search-tools to skip it

check

Run built-in repository checks from VT Code.

Usage

# Install ast-grep if needed
vtcode dependencies install ast-grep

# Materialize the bundled ast-grep scaffold in the current workspace
vtcode init

# Run ast-grep rule tests and scan
vtcode check ast-grep

Notes

  • vtcode check ast-grep runs ast-grep test --config sgconfig.yml and then ast-grep scan --config sgconfig.yml
  • The command expects sgconfig.yml in the workspace root and points you to vtcode init when the scaffold has not been materialized yet

plugins

Manage Agent Plugins — portable packages that bundle Agent Skills and MCP servers under a plugin.json manifest.

# Install a plugin from a git URL or local directory into ~/.agents/plugins
vtcode plugins add https://github.com/example/my-plugin

# List installed plugins with skill and MCP server counts
vtcode plugins list

# Show plugin details
vtcode plugins info my-plugin

# Validate a plugin directory without installing it
vtcode plugins validate ./my-plugin

# Uninstall a plugin
vtcode plugins remove my-plugin

Notes

  • plugins add clones git URLs with git clone --depth=1 and requires local directories to contain a valid plugin.json
  • Plugin MCP servers are exposed as <plugin>.<server> providers and connect at session startup

pods

Manage remote GPU-backed model pods over SSH. See the full feature guide in GPU Pod Manager.

Usage

# Start a pod-backed model
vtcode pods start --name llama \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --ssh "ssh root@gpu.example.com" \
  --gpu 0:A100 --gpu 1:A100 \
  --gpus 2

# Inspect tracked pods
vtcode pods list

# Stream logs for one model
vtcode pods logs --name llama

Commands

  • vtcode pods start - Launch a model on the active pod
  • vtcode pods stop - Stop one tracked model
  • vtcode pods stop-all - Stop every tracked model on the active pod
  • vtcode pods list - Show tracked model status
  • vtcode pods logs - Stream the remote log for a model
  • vtcode pods known-models - Show compatible and incompatible profiles

Did You Mean?

When you type an unrecognized vtcode subcommand, VT Code suggests the closest match:

$ vtcode initilize
# Did you mean?
#   vtcode init

Suggestions use fuzzy matching and are colorized. This also applies to slash commands inside interactive sessions.

Continue / Resume

Resume the most recent archived session:

vtcode --continue
# or in interactive mode:
# /continue

This starts a fresh conversation with the context preserved from the last session. Use it to pick up where you left off after closing VT Code.

Tips

  • The agent respects .vtcodegitignore to exclude files from search and I/O.
  • Prefer exec_command.cmd with rg for fast, focused text searches with glob filters and context.
  • Ask for “N lines of context” when searching to understand usage in-place.
  • Shell commands are filtered by allow/deny lists and can be extended via VTCODE_<AGENT>_COMMANDS_* environment variables.
  • Use vtcode update --check regularly to stay informed about new features and security updates.