An open-source terminal coding agent built in Rust.

Tip

New here? Start with Installation, then Getting Started.

Contents

• Overview
• Quick start
  • 1. Install
  • 2. Configure
  • 3. Run
• Why VT Code
• Architecture
• What's inside
  • Commands
  • Everyday recipes
  • WebMCP browser bridge (opt-in)
• Documentation
• Development
• Contributing
  • Contributors
• Support
  • Contact
  • Share VT Code
  • Sponsorship
• License

Overview

VT Code is a coding agent for your terminal: interactive TUI, headless exec, and scheduled runs in one Rust binary. The model proposes work; the runtime provides tools, context management, and command policy, and you review changes before they land.

Plan, run, and review coding work from your terminal.

Full docs catalog: docs overview.

Note

Status: Active development; some automation flows are experimental. OAuth login for ChatGPT and GitHub Copilot reuses the Codex CLI's public client identity (unofficial); prefer your own API key for supported paths. See OAuth authentication.

Behind the build

• Building VT Code, a year in covering harness design, evals, security, and lessons learned.
• Podcast · Video

Quick start

1. Install

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

The installer also sets up ripgrep and ast-grep on macOS/Linux. Other methods from the installation guide:

brew trust vinhnx/tap
brew install vinhnx/tap/vtcode
# or, if you have Rust: cargo install vtcode

Note

Windows artifacts are best-effort and may lag behind macOS/Linux; see the installation guide.

2. Configure

In your project, initialize workspace instructions and add a provider key:

cd path/to/your/project
vtcode init                # scaffolds config + AGENTS.md; review before committing
vtcode secret add openai   # stores an OpenAI API key in your OS keyring

Any provider works in place of openai. Env vars or a workspace .env also work; vtcode login covers supported OAuth providers. Credential options: Getting started.

Caution

Never commit API keys or put them in vtcode.toml.

3. Run

vtcode   # open the interactive TUI in your project

Ask for a change, inspect the result, keep or discard it. For headless tasks and sessions, see Commands.

Why VT Code

For work that takes more than one prompt:

• Context that persists. Project instructions, context assembly, and compaction for long sessions. Runtime guidance
• Controlled tool use. Command policy and sandboxing at the execution boundary. Security model
• Revisitable sessions. vtcode continue, vtcode trajectory, workspace snapshots. Command reference
• A review path. Plan read-only before implementing; inspect edits in turn diffs. Planning workflow · Diff previews
• Beyond the TUI. Headless vtcode exec, scheduled prompts, MCP, Skills, and Plugins. Full automation · Providers

For repeatable, environment-checked results, use the eval framework; an agent's completion message alone is not a verification result.

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

Loading

The TUI, headless exec/ask, cron schedules, and editors over ACP all drive the same loop. Layers map to workspace crates: entry points in vtcode and vtcode-acp; the harness in vtcode-core (policy and sandboxing in vtcode-safety); the ThreadEvent contract in vtcode-exec-events; extensions in vtcode-mcp, vtcode-skills, and vtcode-agent-plugins; provider clients in vtcode-llm.

Layer-by-layer details: Architecture guide.

What's inside

One binary: TUI, session tools, provider integrations, and an eval runner. MCP servers and plugins need their own setup; see the extension guides.

Commands

Run vtcode for the TUI; pick a subcommand for a specific task:

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

Common commands, flags, and workflows: command reference.

For 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 init	Scaffold vtcode.toml and AGENTS.md in the workspace; review before committing
vtcode exec resume	Continue a finished headless run with a follow-up prompt: --last or a 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 login	OAuth sign-in for ChatGPT and GitHub Copilot; see OAuth authentication
vtcode auth	Show authentication status for one provider or all supported providers
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	Manage skills and agent plugins
vtcode mcp	Connect and manage MCP servers

More: vtcode config, vtcode dependencies, vtcode acp, vtcode a2a, vtcode webmcp, vtcode session-store, vtcode schema (built-in tool schemas), vtcode analyze (workspace structure/security/performance), vtcode check (built-in repository checks), and vtcode man (man pages). Full list: vtcode --help or the command reference.

Everyday recipes

# 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 --name "weekly-dep-audit" --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>

# Continue the last headless run with a follow-up prompt
vtcode exec resume --last "continue the refactor"

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

Pick a specific exec session by id: vtcode exec resume <session-id> "...". Headless exec: exec mode guide · Cron schedules: scheduled tasks guide.

WebMCP browser bridge (opt-in)

Pair the TUI with a browser editor for authenticated, bounded editing:

/webmcp pair <origin>    # inside the TUI

Hosts and deployment: WebMCP user guide.

Documentation

Per-subcommand details are in the command reference.

Layer	Guides
Start	Installation · Getting started · OAuth login · FAQ · Compatibility · Wiki
Use	TUI · CLI · Exec mode · Scheduled tasks · WebMCP
Automate	Automation · Hooks · Planning · Configuration
Extend	Skills · Plugins · MCP · Editors (ACP)
Operate	Safety · Evals · Protocols · Loop engineering · Architecture

Can't find a topic? Documentation Index.

The WebMCP hosted app (mirror) pairs with the TUI bridge; deployment: WebMCP deployment reference.

Development

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]

Loading

Rust stable, edition 2024, MSRV 1.98.1. 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. Details: development overview · testing guide.

Release binaries and notes: GitHub releases (Windows artifacts may lag behind macOS/Linux).

Contributing

Contributions are welcome:

• Code: pick or propose an issue; keep changes surgical and tested.
• Docs: every user-facing feature lands with its documentation.
• Evals: new suites and regression cases are high-leverage; see the eval guide.
• Bug reports: include vtcode trajectory output when possible.

Before a PR: Conventional Commits (type(scope): subject), ./scripts/check-dev.sh + cargo nextest run, focused diff.

Contributors

VT Code is what it is because of the people who build, test, and improve it alongside me. Thank you, all of you.

Show all contributors

Security Advisors

   

Main Contributor

 

Core Contributors

                 

Contributors

                           

Want to see your avatar here? Every bit counts: one-line fixes, bug reports, and feedback are all welcome.

Report a bug · Request a feature · Share feedback · Star the repo · Contribute

Support

Contact

Partnership and collaboration: vinhnguyen2308 [at] gmail [dot] com. Bugs and feature requests: GitHub Issues. Security vulnerabilities: report privately via GitHub private vulnerability reporting; never open a public issue. Details: security policy.

Share VT Code

If VT Code helped you ship something, telling other developers is the easiest way to support the project:

Share on X · Share on Hacker News · Share on LinkedIn · Share via Email · Share via SMS

Sponsorship

VT Code is maintained in spare time. A sponsorship keeps the project independent.

License

First-party code is MIT OR Apache-2.0 (LICENSE); third-party code keeps its original licenses (THIRD-PARTY-NOTICES).