vtcode 0.169.4

An open-source terminal coding agent built in Rust.

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

• Overview
• Spotlight
• Quick start
  • 1. Install
  • 2. Configure
  • 3. Run
• Why VT Code
• Architecture
• Usage
  • Commands
  • Everyday recipes
  • WebMCP browser bridge (opt-in)
• Documentation
• Development
• Contributing
  • Contributors
• Community
  • 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.

[!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.

Spotlight

• Memcode wrote up how VT Code's memory works across threads: read the post. The setup it walks through is documented in the Memcode MCP guide (PR #763).

  "Memory is what creates that compounding loop: each finished task can leave behind a little less uncertainty for the next one, while the developer stays in control of what is saved and when it is used." — Vivek Gupta, Memcode

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

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.

Usage

One binary: TUI, session tools, provider integrations, and an eval runner.

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:

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.

Can't find a topic? Documentation Index.

Full docs catalog: docs overview.

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]

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.

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

Community

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

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).