vtcode 0.169.3

A Rust-based terminal coding agent with modular architecture supporting multiple LLM providers
docs.rs failed to build vtcode-0.169.3
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: vtcode-0.21.8

An open-source terminal coding agent built in Rust.

License Agent Skills Agent Client Protocol Model Context Protocol Agent Plugins Ask DeepWiki

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

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.

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.

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]

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

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.

GitHub Sponsors

License

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