vtcode 0.163.2

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

Secure, open, universal.

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.

The full documentation catalog lives in the docs overview.

[!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

VT Code is built for work that takes more than one prompt. The model reasons; the harness supplies everything else — context, tools, safeguards, state, and verification — so long tasks stay dependable and reviewable from the first prompt to the final diff.

In practice, that means:

The result is a terminal-native workflow that is:

• Inspectable — every run leaves a durable ThreadEvent record you can replay and audit.
• Parallelizable — run isolated loops in git worktrees with propose/verify sub-agents (Loop engineering).
• Extensible — bring your own capabilities via MCP, Skills, Plugins, ACP, A2A, and WebMCP (MCP · Plugins · ACP).
• Keyboard-first — a TUI built for the keyboard, with the terminal remaining the source of truth.
• Scriptable — the same harness drives the TUI, headless exec, eval, and schedule, so interactive and unattended runs behave identically.

VT Code is not just a model producing a plausible next response. It is a runtime you can inspect, resume, extend, and verify.

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.

For contributors, the layers map to workspace crates: entry points live in vtcode (src/) and vtcode-acp; the harness is vtcode-core with vtcode-safety for policy and sandboxing; the ThreadEvent contract is vtcode-exec-events; extensions are vtcode-mcp, vtcode-skills, and vtcode-agent-plugins; provider clients live 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
# 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

The complete CLI surface, flags, and exit codes are documented in the command reference.

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 create --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>

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

Headless exec usage is covered in the exec mode guide; durable cron schedules in the scheduled tasks guide.

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; 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

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.