VT Code

An open-source coding agent for your terminal.

Plan, build, and review with hosted or local models, sandboxed tools, and resumable sessions.

Contents

• VT Code
  • Overview
  • Quick start
    • 1. Install
    • 2. Configure your project
    • 3. Run your first task
  • Usage
    • Interactive
    • Headless
    • Scheduled tasks
    • Sessions
  • Integrations
  • Documentation
  • Development
  • Contributing
  • Security
  • Community
    • Security Advisors
    • Main Contributor
    • Core Contributors
    • Contributors
  • Support the project
    • Resources
    • Share VT Code
    • Sponsorship
  • License

Overview

Use the interactive TUI or vtcode exec to explore a codebase, plan and review changes, and run tools. Choose a model and permission level; VT Code manages context, tool calls, and execution policy.

At a glance	What you get
Planning	Plan read-only, then review turn diffs.
Safety	Auditable command policy and sandboxing.
Self-correct	HOVER loop on tool mismatch.
Long runs	Headless exec with compaction and resumption.
Integrations	MCP, Skills, plugins, and editor bridges.
Models	Hosted or local providers per task.

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]

Loading

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

Start with installation and configuration, then run your first task. The sections below cover interactive use, automation, integrations, and development.

Quick start

Requirements: macOS, Linux, or Windows/WSL. Cargo installs require 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 native installer also attempts to install the optional ripgrep and ast-grep search tools by default. To manage installation yourself, use Homebrew or Cargo; Cargo installs require Rust 1.98.1+:

brew tap 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 tools.

Note

Windows artifacts are best-effort and may lag behind macOS/Linux.

On Windows, install with PowerShell:

irm https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.ps1 | iex

2. Configure your project

In your project directory, scaffold the configuration and agent instructions, then add credentials for your provider. For example, to use OpenAI:

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

Replace openai with your provider. vtcode secret add uses secure storage (OS keyring or encrypted file). You can also set credentials in environment variables or a workspace .env file, or use vtcode login if your provider has 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

Keep API keys out of Git and vtcode.toml. If you use a workspace .env file, make sure it is not committed.

3. Run your first task

vtcode   # open the interactive TUI in your project

Ask a focused question, such as "Explain how this project handles authentication," and review proposed changes and test results before committing. For automation and session commands, see Usage; for a guided walkthrough, see the getting started guide.

Usage

Interactive

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

After a task, /explain summarizes the 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 tool-free answers, exec for tool-enabled coding tasks, 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 <id> to fork an earlier session.

Integrations

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

Integration	What it gives you
MCP	Connect external tools and data sources.
Agent Skills	Load reusable prompt packages on demand.
VT Code Companion (experimental)	Select a compatible VT Code binary and workspace with vtcode companion setup, then install the GitHub marketplace in a local Codex or ChatGPT Desktop host. ChatGPT Local Work and implementation remain experimental.
Plugins	Extend the agent with plugin manifests.
ACP with Zed	Drive VT Code from the Zed editor.
WebMCP	Pair the TUI with an authenticated browser editor via /webmcp pair <origin>; the hosted app (site, mirror) connects through this bridge. See the deployment reference.
Memcode MCP	Carry context between tasks; see the design write-up.

Documentation

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

Goal	Guides
Get started	Installation · Getting started · Providers · OAuth login · FAQ · Compatibility
Work in the TUI	TUI · Command reference · Planning · Turn diffs · Configuration · Safety
Automate	Exec mode · Full automation · Decisions probe · Scheduled tasks · Hooks
Extend and integrate	Skills · Plugins · MCP · Editors (ACP) · WebMCP · Memcode
Develop and evaluate	Development · Testing · Evals · Architecture · HOVER · Protocols · Loop engineering

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]

Loading

To build, use Rust 1.98.1+ (edition 2024); to run tests, install cargo-nextest. See the architecture guide for the full 23-crate map.

Context handling separates session history from provider request projections; local clearing protects complete recent tool batches before automatic compaction. See context architecture and the compaction guide for details.

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.

View all contributors

Security Advisors

   

Main Contributor

 

Core Contributors

                 

Contributors

                             

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.