Skip to content

commands.md

Latest commit

 

History

History
331 lines (236 loc) · 12.5 KB

commands.md

File metadata and controls

331 lines (236 loc) · 12.5 KB

Command Reference

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.

grep_file (ripgrep-like)

High-speed code search with glob filters, context lines, and optional literal/regex matching. VT Code routes searches through the custom grep_file tool. It calls the system rg binary when available, and falls back to the embedded perg engine so downstream tools receive the same JSON response format. Prefer grep_file instead of invoking shell rg/grep yourself.

  • Input fields:

    • pattern (string, required): Search pattern. Treated as regex unless literal=true.
    • path (string, default: .): Base directory to search from.
    • case_sensitive (bool, default: true): Case-sensitive when true.
    • literal (bool, default: false): Treat pattern as literal text when true.
    • glob_pattern (string, optional): Filter files by glob (e.g., **/*.rs).
    • context_lines (integer, default: 0): Lines before/after each hit.
    • include_hidden (bool, default: false): Include dotfiles when true.
    • max_results (integer, default: 1000): Cap results to avoid large payloads.

  • Output fields:

    • matches[]: { path, line, column, line_text, before[], after[] }
    • total_matches, total_files_scanned, truncated

Examples

  • Find TODO/FIXME with 2 lines of context in Rust files only:
Ask: Search for TODO|FIXME across the repo with 2 lines of context in .rs files
(Agent uses grep_file with)
{
  "pattern": "TODO|FIXME",
  "path": ".",
  "case_sensitive": false,
  "glob_pattern": "**/*.rs",
  "context_lines": 2
}
  • Literal search for unsafe { anywhere (hidden files ignored):
{
  "pattern": "unsafe {",
  "literal": true,
  "context_lines": 1
}
  • Search JavaScript files for a function name, case-insensitive:
{
  "pattern": "doSomethingImportant",
  "case_sensitive": false,
  "glob_pattern": "**/*.js"
}

File operations

  • list_files(path, max_items?, include_hidden?)
  • read_file(path, max_bytes?)
  • write_file(path, content, mode?) — mode: overwrite, append, or skip_if_exists
  • edit_file(path, old_str, new_str) — tolerant to whitespace differences and detects rename conflicts

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.
  • /loop schedules a session-scoped prompt that re-enters the chat only when the current turn is idle.
  • /schedule manages durable scheduled tasks. They are polled while VT Code is open, and the local scheduler daemon keeps them running in the background.

Scheduled tasks

Use /loop inside interactive chat for quick polling, and 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 unified_search --name unified_file

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

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

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

Tips

  • The agent respects .vtcodegitignore to exclude files from search and I/O.
  • Prefer grep_file for fast, focused 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.