vtcode 0.162.3

Secure, open, universal terminal coding agent 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
  • Sponsorship
• License

Overview

VT Code is an open-source terminal coding agent written in Rust: one static binary for quick interactive sessions and long-running autonomous work alike — no IDE required, no context left behind. It is a harness, not just an LLM wrapper: the model reasons; the runtime supplies everything else — tools, context, sandboxing, state, and verification — turning raw model output into safe, reviewable progress, entirely in your terminal.

[!NOTE] Status: Active development. Local inference and some automation flows are experimental and may change between releases.

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

Why VT Code

Most agents are a model plus a tool call. VT Code answers each common failure mode with a structural default in the runtime, not a prompt tweak:

Underneath all four: one ThreadEvent stream records everything a run did, and the agent loop contract specifies how turns, tool results, and recovery behave. Extensibility is structural too: every major model sits behind one interface, and MCP, Skills, Plugins, ACP, A2A, and WebMCP attach without forking (MCP · Providers). The interface is a keyboard-first TUI with WCAG AA themes, gated by cargo nextest and CI with -D warnings (Testing).

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

• Entry points: the TUI, headless exec/ask, cron schedules, and editors over ACP all drive the same loop.
• Harness: context assembly, policy checks, and sandboxing wrap every model turn; the ThreadEvent log records everything for replay and rollback.
• Extensions and models: attach without patching the core; swap providers without touching your workflow.

Quick start

1. Install

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# or: brew install vinhnx/tap/vtcode
# or: cargo install vtcode

2. Configure

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

/secret add <provider> inside the TUI does the same. vtcode login covers OAuth providers (ChatGPT, GitHub Copilot); plain env vars and workspace .env still work for CI. See Getting started for the credential resolution order.

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

3. Run

vtcode                  # interactive TUI — the whole loop is install, init, run

See Commands for the complete CLI surface, including headless exec, one-shot ask, and session resume.

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

One static Rust binary: no runtime dependencies, no plugins to install, nothing to wire up. Everything below ships in the default build.

At a glance: durable sessions · sandboxed execution · every major model · MCP, Skills & plugins · terminal-native TUI · built-in evals

Commands

Bare vtcode opens the interactive TUI. Four subcommands cover most of the work:

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

A second tier handles session lifecycle and day-to-day operations:

vtcode analyze, vtcode check, vtcode schema tools, vtcode man, and vtcode update round out the operator surface. See vtcode --help for the full list.

Everyday recipes

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

# Nightly dependency audit as a durable cron job
vtcode schedule add --cron "0 9 * * 1" "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>

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

Documentation

The full catalog lives in 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
    types --> config --> core --> tools --> agent --> TUI

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.
• 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

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.