vtcode 0.169.1

An open-source terminal coding agent built in Rust.

[!TIP] New here? Start with Installation, then Getting Started.

• Overview
• Why VT Code
• Architecture
• Quick start
  • 1. Install
  • 2. Configure
  • 3. Run
  • WebMCP browser bridge (opt-in)
• What's inside
  • Commands
  • Everyday recipes
• Documentation
• Development
• Contributing
  • Contributors
• Support
  • Contact
  • Sponsorship
• License

Overview

Plan, run, and review coding work from your terminal.

VT Code brings an interactive coding agent, headless tasks, and session history into a single Rust binary. The model proposes work; the runtime provides tools, context management, command policy, and a record you can inspect. Use it from the terminal without an IDE, and review changes before you keep them.

The full documentation catalog lives in the docs overview.

[!NOTE] Status: Active development. Some automation flows are experimental and may change between releases. OAuth login for ChatGPT and GitHub Copilot reuses the Codex CLI's public client identity as an unofficial compatibility mechanism — bring your own provider API key if you need a supported path. See OAuth authentication.

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

Why VT Code

For work that takes more than one prompt, VT Code offers:

• Context for ongoing work. Project instructions, context assembly, and compaction help manage longer sessions. Runtime guidance
• Controls for tool use. Command policy and sandboxing apply at the execution boundary; review the security model for their limits and configuration.
• Sessions you can revisit. Resume with vtcode continue, inspect run history with vtcode trajectory, and manage workspace snapshots. Command reference
• A review path. Plan read-only before approving implementation, and inspect completed edits in turn diffs. Planning workflow · Diff previews
• Options beyond the TUI. Run headless tasks with vtcode exec, schedule prompts, connect providers, and extend the tool surface with MCP, Skills, and Plugins. Unattended runs require workspace trust and automation setup. Full automation · Providers

For repeatable, environment-checked results, use the separate eval framework; an agent's completion message alone is not a verification result.

Architecture

One binary, four layers. Everything the model touches goes through the harness; nothing bypasses it.

graph LR
    subgraph entry [Entry points]
        TUI[TUI]
        CLI[CLI / exec / cron]
        ACP[Editor via ACP]
    end

    subgraph harness [Harness]
        LOOP[Agent loop]
        CTX[Context assembly + compaction]
        SEC[Tool policy + sandboxed exec]
        EVT[(ThreadEvent log)]
    end

    subgraph ext [Extensions]
        MCPX[MCP servers]
        SKILLS[Skills]
        PLUGINS[Plugins]
    end

    MODELS[OpenAI · Anthropic · Gemini · local]

    TUI --> LOOP
    CLI --> LOOP
    ACP --> LOOP
    LOOP --> CTX
    LOOP --> SEC
    LOOP <--> EVT
    LOOP <--> ext
    LOOP <--> MODELS

The TUI, headless exec/ask, cron schedules, and editors over ACP all drive the same loop. For contributors, the layers map to workspace crates: entry points in vtcode (src/) and vtcode-acp; the harness in vtcode-core with vtcode-safety for policy and sandboxing; the ThreadEvent contract in vtcode-exec-events; extensions in vtcode-mcp, vtcode-skills, and vtcode-agent-plugins; provider clients in vtcode-llm.

For layer-by-layer details, extension seams, and internal composition rules, see the Architecture guide.

Quick start

1. Install

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

On macOS or Linux, the installer also attempts to install ripgrep and ast-grep. For other methods, see the installation guide:

brew trust vinhnx/tap
brew install vinhnx/tap/vtcode
# or, if you have Rust: cargo install vtcode

2. Configure

In your project, initialize workspace instructions and add a provider key:

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

Use your own provider in place of openai. If you already use environment variables or a workspace .env, you can use those instead of storing a key; vtcode login is available for supported OAuth providers. See Getting started for credential options.

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

3. Run

vtcode   # open the interactive TUI in your project

You can now ask for a change, inspect the result, and decide whether to keep it. For headless tasks, one-shot questions, or resuming a session, see Commands.

WebMCP browser bridge (opt-in)

Pair the TUI with a browser editor for authenticated, bounded workspace editing:

/webmcp pair <origin>    # inside the TUI

See the WebMCP user guide for hosts and deployment.

What's inside

The Rust binary includes the TUI, session tools, provider integrations, and an eval runner. Optional integrations such as MCP servers and plugins need their own setup; see the extension guides.

Commands

Run vtcode for the interactive TUI. Choose a subcommand for a specific task:

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
vtcode eval --suite suite.json    # verify behavior with pass@k metrics

The most common commands, flags, and workflows are documented in the command reference; run vtcode --help for the full subcommand list.

For session lifecycle and day-to-day operations:

For the full command list, use vtcode --help or the command reference. Further commands cover configuration and dependencies (vtcode config, vtcode dependencies), editor/agent bridges (vtcode acp, vtcode a2a, vtcode webmcp), and the state store (vtcode session-store).

Everyday recipes

# Review only the uncommitted diff, then exit with a verdict
vtcode review

# Weekly dependency audit (Mondays 09:00) as a durable cron job
vtcode schedule create --name "weekly-dep-audit" --cron "0 9 * * 1" --prompt "check for outdated deps and open an issue if any have CVEs"

# Resume yesterday's session and fork it for a new experiment
vtcode continue --session-id <id>

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

# See exactly what the agent did in the last run
vtcode trajectory

To pick up a specific exec session by id, use vtcode exec resume <session-id> "...". Headless exec usage: exec mode guide. Durable cron schedules: scheduled tasks guide.

Documentation

Start with Installation and Getting Started. For individual subcommands, use the command reference. The guides below cover specific workflows and integrations.

Can't find a topic? Browse the Documentation Index.

The WebMCP hosted app (fallback mirror) pairs with the TUI bridge; deployment details live in the WebMCP deployment reference.

Development

graph LR
    BIN[vtcode binary] --> CORE[vtcode-core harness]
    CORE --> LLM[vtcode-llm]
    CORE --> SAFETY[vtcode-safety]
    CORE --> EVENTS[vtcode-exec-events]
    CORE --> UI[vtcode-ui]

Rust stable, edition 2024, MSRV 1.93. Clone and run the fast gate:

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 (10-30s)
cargo nextest run          # tests (never `cargo test`)

CI runs with RUSTFLAGS="-D warnings" and --locked; match locally with cargo check --locked. See the development overview and testing guide for details.

Contributing

Contributions are welcome:

• Code: pick an open issue or propose one; keep changes surgical and covered by tests.
• Docs: fixes and new guides in docs/; every user-facing feature should land with its documentation.
• Evals: new suites and regression cases are high-leverage contributions; see the eval guide for suite authoring and metrics.
• Bug reports: include vtcode trajectory output when possible; it makes runs reproducible.

Before opening a PR: follow Conventional Commits (type(scope): subject), run ./scripts/check-dev.sh and cargo nextest run, and keep the diff focused.

Contributors

Thank you to everyone who shaped VT Code.

Support

Contact

For partnership and collaboration inquiries: vinhnguyen2308 [at] gmail [dot] com

For bugs and feature requests, prefer GitHub Issues.

Sponsorship

VT Code is built and maintained in spare time. If it helped you ship or learn something, a sponsorship keeps the project independent.

License

First-party code is MIT OR Apache-2.0. See LICENSE. Third-party code keeps its original licenses: see THIRD-PARTY-NOTICES.