vtcode 0.171.2

An open-source terminal coding agent built in Rust.

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

• Overview
• Quick start
  • 1. Install
  • 2. Configure your project
  • 3. Start an interactive session
• Workflows
  • Interactive work
  • Headless automation
  • Scheduled tasks
  • Session management
  • Optional integrations
• Documentation
• Development
• Contributing
  • Contribute
• Community
  • Contributors
  • Contact
  • Resources
  • Share VT Code
  • Sponsorship
• License

Overview

VT Code is an open-source terminal coding agent built in Rust. Explore a codebase, plan changes, run tools, and review edits in the interactive TUI, or run vtcode exec headless. You pick the model and permissions; the runtime handles context, tools, and execution policy, and you review every change before it lands.

• Plan and review: read-only planning mode, then inspect edits in turn diffs.
• Sustain long sessions: project instructions, context compaction, resumption, execution logs.
• Control execution: command policy and sandboxing at the boundary.
• Choose your stack: hosted or local models, plus MCP servers, Agent Skills, and Plugins.

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

[!NOTE] Status: Active development; some automation flows are experimental.

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. Or use Homebrew or Cargo:

brew trust vinhnx/tap
brew install vinhnx/tap/vtcode

# Or install with Rust
cargo install vtcode

See the installation guide for prerequisites, other methods, and the installer script you can review before running.

[!NOTE] Windows artifacts are best-effort and may lag behind macOS/Linux.

2. Configure your project

Open your project, initialize its configuration and instructions, then add credentials for your chosen provider. For example, with OpenAI:

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

Replace openai with your supported provider. Credentials can also come from environment variables or a workspace .env; vtcode login handles supported login flows. See Getting started and Provider guides.

[!NOTE] ChatGPT OAuth reuses the Codex CLI's public client identity through an unofficial compatibility flow; prefer your own OpenAI API key. GitHub Copilot uses the official copilot CLI. See OAuth authentication.

[!CAUTION] Never commit API keys or put them in vtcode.toml.

3. Start an interactive session

vtcode   # open the interactive TUI in your project

Start with a focused request, such as “Explain how this project handles authentication,” then review the diff and test results before committing. For automation and session commands, see Workflows.

Workflows

Interactive work

Use vtcode to explore a codebase, plan a change, and implement it in the TUI. For larger tasks, start with read-only planning and review turn diffs before committing. See the interactive guide for controls.

Headless automation

Use ask for a tool-free answer and exec for a tool-enabled coding 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

exec needs autonomous execution enabled in [automation.full_auto] plus full_auto workspace trust. In a terminal, an untrusted workspace prompts for trust; in CI or another non-TTY environment, grant trust beforehand or set VTCODE_TRUST_WORKSPACE=full-auto; otherwise non-TTY runs fail rather than prompt. Full-auto's tool allow-list, explicit denies, and execution policy still apply. See exec mode for trust and output options and full automation for configuration.

For repeatable, environment-checked results, use the eval framework: a completion message alone is not verification.

Scheduled tasks

For recurring work, use scheduled tasks: durable prompt jobs on the same exec runtime:

# Weekly dependency audit (Mondays 09:00)
vtcode schedule create --name "weekly-dep-audit" \
  --cron "0 9 * * 1" \
  --prompt "Check for outdated dependencies and report known vulnerabilities"

Session management

# Resume the most recent interactive session
vtcode continue

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

# Inspect the execution log
vtcode trajectory

Use vtcode continue --session-id <id> to fork an earlier session. See vtcode --help or the command reference for all commands and flags.

Optional integrations

Enable these only when you need them; none are required for the quick start.

• Tools and extensions: MCP servers, Agent Skills, and Plugins.
• Editors: ACP with Zed.
• Cross-thread memory: Memcode MCP carries context between tasks; see the write-up.
• Browser editing: WebMCP pairs the TUI with an authenticated browser editor:

/webmcp pair <origin>    # inside the TUI

The hosted app at vtcode.vinhnx.chatgpt.site (mirror) uses this authenticated, workspace-scoped bridge. Setup and deployment: WebMCP user guide · deployment reference.

Documentation

Guides by task; the full catalog lives in the documentation index, the docs overview, and the Wiki:

Development

graph LR
    BIN[vtcode binary] --> CORE[vtcode-core harness]
    BIN --> EVAL[vtcode-eval]
    CORE --> LLM[vtcode-llm]
    CORE --> SAFETY[vtcode-safety]
    CORE --> EVENTS[vtcode-exec-events]
    CORE --> CONFIG[vtcode-config]
    CORE --> MEMORY[vtcode-memory]
    CORE --> UI[vtcode-ui]

Full 23-crate workspace map: Architecture guide. Requires Rust 1.98.1+ (edition 2024) and cargo-nextest for tests:

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
cargo nextest run          # tests (requires cargo-nextest)

CI sets RUSTFLAGS="-D warnings" and builds with --locked; match locally with RUSTFLAGS="-D warnings" cargo check --locked. Setup and checks: development overview · testing guide.

Release binaries and notes: GitHub releases.

Contributing

Contribute

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, and a focused diff.

Community

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

Contact

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

Resources

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

Share VT Code

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

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 it independent.

License

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