VT Code

Overview

Explore a codebase, plan changes, run tools, and review edits, in the interactive TUI or headless with vtcode exec. You pick the model and the permissions; the runtime handles context management, tool calls, and execution policy.

flowchart LR
    H[Hypothesize] --> O[Observe tool evidence]
    O --> V[Verify outcome]
    V --> E[Evaluate vs hypothesis]
    E -->|mismatch| R[Revise and retry corrected]
    R --> H
    E -->|match| D[Done]

Legend: H states the expected outcome; O collects bounded tool evidence; V checks exit status and verifier result; E compares expectation against evidence; R applies an evidence-supported correction. mismatch (non-zero exit, empty search, stale patch, failed verifier, repeated evidence) loops back with corrected arguments; match exits to Done. Rereads alone are not revision. Full acceptance table: HOVER validation.

The rest of this page covers installation, configuration, a first task, and the deeper topics.

Quick start

Requirements: macOS, Linux, or Windows/WSL. Installing with Cargo also requires Rust 1.98.1+ (edition 2024).

1. Install

# Review the installer script before running it: https://github.com/vinhnx/vtcode/blob/main/scripts/install.sh
curl -fsSL https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.sh | bash

On macOS and Linux, the installer also installs ripgrep and ast-grep by default. Prefer Homebrew or Cargo if you want to manage the installation yourself:

brew trust vinhnx/tap
brew install vinhnx/tap/vtcode

# Or install with Rust (requires Rust 1.98.1+)
cargo install vtcode

Run vtcode --version to verify the installation. The installation guide covers prerequisites, other install methods, and optional search-tool setup.

[!NOTE] Windows artifacts are best-effort and may lag behind macOS/Linux.

2. Configure your project

From your project directory, scaffold the project configuration and agent instructions, then add credentials for your chosen provider. For example, with OpenAI:

cd path/to/your/project
vtcode init                # scaffolds config + AGENTS.md; review before committing
vtcode secret add openai   # stores an OpenAI API key in your OS keyring

Replace openai with your provider. Alternatively, set credentials in environment variables or a workspace .env file, or use vtcode login for a supported login flow. See Getting started and Provider guides for provider-specific instructions.

[!NOTE] ChatGPT OAuth reuses the Codex CLI’s public client identity via an unofficial compatibility flow; prefer your own OpenAI API key. GitHub Copilot uses the official copilot CLI. See OAuth authentication.

[!CAUTION] Never commit API keys or put them in vtcode.toml.

3. Run your first task

vtcode   # open the interactive TUI in your project

Start with a focused request, such as “Explain how this project handles authentication.” Review proposed changes and test results before committing. See Usage for automation and session commands, or take the guided tour.

Usage

Interactive

Use vtcode to explore, plan, and implement changes in the TUI. For larger tasks, begin with read-only planning, then review the turn diff before committing. The interactive guide covers controls.

After a task, /explain reviews outcome, changes, decisions, verification, and review priorities without another model call:

• /explain --details adds evidence.
• /explain diagram shows execution relationships.
• /explain --web opens the browser view with an offline fallback.
• /explain --export html saves a standalone report.

Scopes and report options: explanation usage.

Headless

Use ask for a tool-free answer, exec for a tool-enabled coding task, and review to inspect uncommitted changes:

vtcode ask "explain Rc vs Arc"    # one-shot answer, no session, no tools
vtcode exec "refactor main.rs"    # headless task with the full tool loop
vtcode review                     # agent review of uncommitted changes

exec runs the full tool loop and requires [automation.full_auto] plus full_auto workspace trust. Interactive terminals prompt for trust. Non-TTY runs require VTCODE_TRUST_WORKSPACE=full-auto; tool allow-lists, explicit denies, and execution policy still apply. See exec mode and full automation for configuration and output details.

For repeatable, environment-checked results, use the eval framework. A completion message alone is not verification.

Scheduled tasks

For recurring work, use scheduled tasks: durable prompt jobs on the same exec runtime.

# Weekly dependency audit (Mondays 09:00)
vtcode schedule create --name "weekly-dep-audit" \
  --cron "0 9 * * 1" \
  --prompt "Check for outdated dependencies and report known vulnerabilities"

Sessions

Resume or inspect earlier work:

# Resume the most recent interactive session
vtcode continue

# Continue the last headless run with a follow-up prompt
vtcode exec resume --last "continue the refactor"

# Inspect the execution log
vtcode trajectory

Use vtcode continue --session-id to fork an earlier session.

Integrations

Enable these only when you need them; none are required for the quick start.

Documentation

Guides grouped by task. The full catalog lives in the documentation index, the docs overview, and the Wiki:

Development

graph LR
    BIN[vtcode binary] --> CORE[vtcode-core harness]
    BIN --> EVAL[vtcode-eval]
    CORE --> LLM[vtcode-llm]
    CORE --> SAFETY[vtcode-safety]
    CORE --> EVENTS[vtcode-exec-events]
    CORE --> CONFIG[vtcode-config]
    CORE --> MEMORY[vtcode-memory]
    CORE --> UI[vtcode-ui]

Building requires Rust 1.98.1+ (edition 2024); tests need cargo-nextest. The full 23-crate map lives in the architecture guide.

Context handling separates session history from provider request projections. Local clearing protects complete recent tool batches; headless runs estimate the cleared projection before automatic compaction. See context architecture and the compaction guide for budgets, provider strategies, and persistence boundaries.

git clone https://github.com/vinhnx/VTCode.git
cd VTCode
./scripts/run-debug.sh     # build and launch a debug binary
./scripts/check-dev.sh     # fast gate: clippy, fmt, check
cargo nextest run          # tests (requires cargo-nextest)

CI builds with --locked and RUSTFLAGS="-D warnings"; match locally with RUSTFLAGS="-D warnings" cargo check --locked. Setup and checks are documented in the development overview and the testing guide.

Release binaries and notes: GitHub releases.

Contributing

Contributions are welcome in every form:

• Code: pick or propose an issue; keep changes surgical and tested.
• Docs: every user-facing feature lands with its documentation.
• Evals: new suites and regression cases are high-leverage; see the eval guide.
• Bug reports: include vtcode trajectory output when possible.

Before a PR, see the contribution guide: Conventional Commits (type(scope): subject), ./scripts/check-dev.sh + cargo nextest run, and a focused diff.

Security

Report vulnerabilities privately via GitHub private vulnerability reporting; never open a public issue. Details: security policy.

Community

Thanks to everyone who builds, tests, and improves VT Code. For partnerships, reach the maintainer at vinhnguyen2308 [at] gmail [dot] com; bugs and feature requests belong in GitHub Issues.

Want to see your avatar here? Every bit counts: one-line fixes, bug reports, and feedback are all welcome.

Report a bug · Request a feature · Share feedback · Star the repo · Contribute

Support the project

Resources

• Building VT Code, a year in: harness design, evals, security, and lessons learned.
• Podcast · Video

Share VT Code

If VT Code helped you ship something, spread the word:

Share on X · Share on Hacker News · Share on LinkedIn · Share via Email · Share via SMS

Sponsorship

VT Code is maintained in spare time; a sponsorship keeps it independent.

License

First-party code is MIT OR Apache-2.0 under LICENSE. Third-party code keeps its original licenses, listed in THIRD-PARTY-NOTICES.