Secure, open, universal terminal coding agent in Rust.
Tip
New here? Start with Installation, then Getting Started.
Contents
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.
Note
Status: Active development. Local inference and some automation flows are experimental and may change between releases.
Behind the build
- Building VT Code, a year in covering harness design, evals, security, and lessons learned.
- Podcast · Video
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:
| Failure mode | Structural answer |
|---|---|
| Sessions drift | Dynamic context assembly and auto-compaction keep long sessions grounded. Runtime guidance |
| Tool output floods the window | Results spool to disk and are summarized into context on demand; signal stays in, noise stays out. |
| One unreviewed command | Sandboxed, fail-closed execution with adversarial coverage for injection, path/symlink escape, and environment leakage. Security model |
| "Done" is a claim | Built-in evals with pass@k / pass^k and environment-based verification: the agent's own report never counts as success. Eval guide |
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).
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
ThreadEventlog records everything for replay and rollback. - Extensions and models: attach without patching the core; swap providers without touching your workflow.
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# or: brew install vinhnx/tap/vtcode
# or: cargo install vtcodecd 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.
vtcode # interactive TUI — the whole loop is install, init, runSee Commands for the complete CLI surface, including headless
exec, one-shot ask, and session resume.
Pair the TUI with a browser editor for authenticated, bounded workspace editing:
/webmcp pair <origin> # inside the TUISee the WebMCP user guide for hosts and deployment.
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
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 metricsA second tier handles session lifecycle and day-to-day operations:
| Command | Purpose |
|---|---|
vtcode continue |
Resume the last session, or fork it into a new one with --session-id |
vtcode schedule |
Durable recurring prompts, by cron or one-shot; install-service survives restarts |
vtcode secret |
Store provider API keys in your OS keyring, never in shell history or workspace files |
vtcode models |
Inspect, test, and compare providers and models |
vtcode snapshots / vtcode revert |
List and roll back to workspace snapshots |
vtcode tool-policy |
Allow or deny specific tools per workspace |
vtcode trajectory |
Pretty-print run logs for debugging and audits |
vtcode analyze, vtcode check, vtcode schema tools, vtcode man, and
vtcode update round out the operator surface. See vtcode --help for the
full list.
# 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| Layer | Guides |
|---|---|
| Start | Installation · Getting started · Wiki |
| Use | TUI · CLI · WebMCP · Automation · Planning · Configuration |
| Extend | Skills · Plugins · MCP · Editors (ACP) |
| Operate | Safety · Protocols · Loop engineering · Architecture |
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.
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.
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 trajectoryoutput 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.
Thank you to everyone who shaped VT Code.
Show all contributors
VT Code is built and maintained in spare time. If it helped you ship or learn something, a sponsorship keeps the project independent.
First-party code is MIT OR Apache-2.0. See LICENSE. Third-party code keeps its original licenses: see THIRD-PARTY-NOTICES.