vtcode 0.162.1

Secure, open, universal terminal coding agent in Rust.

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

• Overview
• Why VT Code
• Quick start
  • 1. Install
  • 2. Configure
  • 3. Run
  • WebMCP browser bridge (opt-in)
• What's inside
• Documentation
• Providers
• Development
• Contributing
  • Ways to contribute
  • Getting started
  • Contributors
• Support
  • Sponsorship
• License

Overview

VT Code is an open-source terminal coding agent written in Rust — one tool 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. That separation is what turns 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.

[!TIP] Behind the build: Building VT Code, a year in — harness design, evals, security, and lessons from a year of building.

Video companions: Podcast · Video.

Why VT Code

Most agents are a model plus a tool call. That gets you a demo, not a teammate. Real work breaks them in predictable ways:

• Sessions drift. After an hour of edits, the model reasons over stale context and redoes work you already finished.
• Tool output floods the window. One verbose command pushes the parts that mattered out of the model's view.
• One unreviewed command can take out your working tree — or worse.
• "Done" is a claim, not a fact. Without verification, you find out the agent failed the same way your users would.

VT Code treats the agent loop itself as the product. The model reasons; the harness supplies everything else — tools, context, sandboxing, state, and verification — and answers each failure mode with a structural default, not a prompt tweak:

The same discipline shapes everything else. The four pillars below cover it in depth: extensibility without forking, autonomy earned with evidence, every model behind one abstraction, and a terminal-native interface verified by default.

Under the hood, the loop contract is explicit and testable. ThreadEvent is the single source of truth for what happened during a run, and the agent loop contract specifies exactly how turns, tool results, and recovery behave. The behavior you rely on is written down — not accidental.

If you have been burned by agents that look impressive until something goes wrong, these are the defaults you were missing — built in, not bolted on.

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

Set your API key — the TUI's /secret command stores it in your OS keyring (never in a workspace .env or shell history), which is the most secure option:

vtcode secret add openai   # headless; or run /secret add openai inside the TUI

vtcode login covers OAuth providers (ChatGPT, GitHub Copilot). Plain env vars and workspace .env still work — useful 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
vtcode ask "explain Rc vs Arc"  # one-shot question
vtcode exec "refactor main.rs"  # headless task
vtcode review                   # review uncommitted changes
vtcode continue                 # resume the last session

See Installation and Getting Started for the full tour, and Commands for the complete CLI surface.

WebMCP browser bridge (opt-in)

# Inside the TUI:
/webmcp pair <origin>

# Or serve a bounded workspace:
vtcode webmcp serve --origin <origin> --allowed-root <dir>

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.

Four pillars

The rest of this section expands each pillar in turn:

Agent core

The loop that turns model output into reviewable progress.

• Durable sessions — checkpoints, auto-compaction, and spooled tool output keep hour-long runs grounded. continue resumes; revert rolls back to a snapshot. (Runtime guidance · Session persistence)
• One event contract — a single ThreadEvent stream drives replay, the session store, memory, and trajectory export. One history, never divergent copies. (Agent loop contract)
• Planning & autonomy — planning gates, propose/verify sub-agents, isolated worktrees, and cost guardrails. Autonomy is earned with evidence, not granted up front. (Planning workflow · Full automation)
• Persistent memory — gotchas, decisions, and library notes survive across runs, so the agent stops re-learning your project every session. (Memory management)

Safety

Fail closed by default, with coverage for the attacks that actually happen.

• Sandboxed execution — command policies and workspace approvals fail closed: injection, path/symlink escape, and environment leakage are blocked before anything runs. (Security model · Permissions)
• Syntax-aware command parsing — tree-sitter decomposes shell pipelines into sub-commands, so every piece is validated against policy — not just the first word. (Tree-sitter integration)
• Hooks & tool policies — lifecycle hooks gate tool calls before they run; per-tool allow/deny rules run common dev tools automatically and require confirmation for dangerous operations. (Hooks guide · Execution policy)

Extensibility

Plug in without forking — your setup survives upgrades.

• Every model, one abstraction — first-party APIs (OpenAI, Anthropic, Gemini, DeepSeek, Qwen, Mistral, xAI, …), gateways (OpenRouter, Vercel AI Gateway), OpenAI-compatible endpoints, and local inference (Ollama, LM Studio, llama.cpp) behind one streaming interface. Switching models never changes your workflow. (Provider guides · Local models)
• Integrations — MCP servers, Agent Skills, Agent Plugins, ACP (Zed), A2A, and the WebMCP browser bridge all attach to the core without patching it. (MCP · Skills · Plugins · ACP · A2A · WebMCP)
• Embed VT Code — serve the agent over ACP for editors, expose an Anthropic-compatible API with vtcode anthropic-api, or proxy to the Codex app-server. VT Code works as a backend, not just a CLI. (ACP · Protocols)

[!TIP] Manage models with vtcode models list|config|test|compare|info, restrict providers per workspace via providers_whitelist in vtcode.toml, and control local inference with /local in the TUI. Provider guides are the source of truth for credentials and model defaults.

Interface & quality

Native to the terminal, verified by default.

• Terminal-native TUI — WCAG AA-validated themes, markdown rendering, diff previews, and customizable output styles and status line. Built for the terminal, not ported to it. (Interactive mode · Output styles)
• Headless & automation — exec mode, scheduled tasks, and sub-agents cover scripted, parallel, and unattended work. (Exec mode · Scheduled tasks · Sub-agents)
• Evals — pass@k / pass^k metrics with environment-based verification. The agent's own report never counts as success. (Eval guide)

[!TIP] Optional search accelerators (ripgrep, ast-grep) install with vtcode dependencies install search-tools.

Documentation

The full catalog lives in the Documentation Index.

Development

graph LR
    types --> config --> core --> tools --> agent --> TUI

Clone and run the fast gate:

git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh
./scripts/check-dev.sh   # fast gate: clippy, fmt, check
cargo nextest run        # tests (never `cargo test`)

Rust stable, edition 2024, MSRV 1.93. ~30 crates layered as types → config → core → tools → agent → TUI, with ThreadEvent as the authoritative runtime contract.

See Development setup and Testing.

Contributing

Ways to contribute

• Security: Found a vulnerability? Follow the Security Policy.
• Bug fixes and patches: Small or large, every fix counts.
• Documentation: Guides, examples, and corrections help everyone.
• Features and ideas: Open an issue or start a discussion.
• Code reviews and testing: Trying things out and reporting breakage keeps the project healthy.

Getting started

• Browse good first issues
• Read CONTRIBUTING.md for humans
• Check AGENTS.md for AI agents

[!NOTE] Small, focused PRs merge fastest. If you get stuck, open an issue for help.

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.

Back to top