vtcode 0.162.2

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
  • Commands
  • Four pillars
    • Agent core
    • Safety
    • Extensibility
    • Interface & quality
• Documentation
• 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 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. 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 covers 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, and VT Code answers each one with a structural default, not a prompt tweak:

None of this is emergent. ThreadEvent is the single source of truth for what happened during a run: one event stream feeds replay, checkpoints, memory, and trajectory export. The agent loop contract specifies 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. The four pillars below cover the full surface, or skip to Quick start and see it work.

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 "…"          # one-shot question, no session, no tools
vtcode exec "…"         # headless task with the full tool loop
vtcode continue         # resume the last session

That is the whole loop: install, init, run. See Commands for the complete CLI surface, and Getting Started for the full tour.

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

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: seeTHIRD-PARTY-NOTICES.

Back to top