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.
The full documentation catalog lives in the docs overview.
Note
Status: Active development. Some automation flows are experimental and may change between releases. OAuth login for ChatGPT and GitHub Copilot reuses the Codex CLI's public client identity as an unofficial compatibility mechanism — bring your own provider API key if you need a supported path. See OAuth authentication.
Behind the build
- Building VT Code, a year in covering harness design, evals, security, and lessons learned.
- Podcast · Video
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:
| What can go wrong | How VT Code responds |
|---|---|
| Long tasks lose focus | Dynamic context assembly, project instructions, auto-compaction, and bounded tool output keep the active window useful. Runtime guidance · Architecture |
| Generated commands can cause damage | Policy checks and sandboxed, fail-closed execution defend against injection, path and symlink escape, and environment leakage. Security model |
| A session is interrupted | Resume with vtcode continue, fork with --session-id, and inspect or restore changes with vtcode snapshots and vtcode revert. Commands |
| “Done” is asserted without proof | Built-in evals verify the environment instead of trusting the agent's report, measured with pass@k and pass^k. Eval guide |
| Big changes ship unreviewed | The Planning Workflow keeps planning read-only: draft with /plan, approve at a review gate, then hand off to build or auto. Planning workflow |
| Edits land unseen | Completed edits render as bounded, themed turn diffs with highlighting, so you review changes before they stack up. Diff previews |
| Setup and teardown stay manual | Lifecycle hooks run shell commands on session and tool events; workspace hooks need explicit approval first. Hooks guide |
| Edits drift from project conventions | Project instructions (AGENTS.md) are loaded into every turn, so the agent codes to your rules instead of rediscovering them. Getting started |
| Interactive only is not enough | Headless vtcode exec with JSON events, scheduled tasks via vtcode schedule, and isolated eval worktrees support CI, cron, and agent-to-agent flows. Full automation |
| One provider locks you in | Built-in adapters for Gemini, OpenAI, Anthropic, DeepSeek, xAI, Meta, NVIDIA NIM, and more — plus gateways such as OpenRouter and GitHub Copilot, OpenAI-compatible custom providers, local inference via Ollama, LM Studio, and llama.cpp, and a providers_whitelist for air-gapped setups. Providers |
The result is a terminal-native workflow that is:
- Inspectable — every run leaves a durable
ThreadEventrecord 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, andschedule, 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.
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.
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.
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# or: brew trust vinhnx/tap && 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 most common commands, 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 metricsThe most common commands, flags, and workflows are documented in the
command reference; run vtcode --help for
the full subcommand list.
A 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 skills / vtcode plugins / vtcode mcp |
Manage skills, agent plugins, and MCP servers |
vtcode analyze, vtcode check, vtcode schema tools, vtcode dependencies
(alias deps), vtcode config, vtcode man, and vtcode update round out
the operator surface, with editor/agent bridges (vtcode acp, vtcode a2a,
vtcode webmcp) and the state store (vtcode session-store) alongside. See
vtcode --help for the full list.
# Review only the uncommitted diff, then exit with a verdict
vtcode review
# Weekly dependency audit (Mondays 09:00) 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 trajectoryHeadless exec usage is covered in the
exec mode guide; durable cron schedules in
the scheduled tasks guide.
| 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
BIN[vtcode binary] --> CORE[vtcode-core harness]
CORE --> LLM[vtcode-llm]
CORE --> SAFETY[vtcode-safety]
CORE --> EVENTS[vtcode-exec-events]
CORE --> UI[vtcode-ui]
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; see the eval guide for suite authoring and metrics.
- 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.
