VT Code

Plan, change, and verify code from your terminal, with every step auditable.

VT Code is an open-source coding agent for your repository. Choose the model, keep tool calls under policy, and review every change.

Contents

• Contents
• Overview
• Quick start
  • 1. Install
  • 2. Configure your project
  • 3. Run your first task
• Usage
  • Interactive
  • Modes
  • Automation
  • Sessions
• Documentation
  • Get started
  • Work in the TUI
  • Automate
  • Extend and integrate
  • Develop and evaluate
• Development
• Contributing
• Security
• Community
• Thanks to our contributors
  • Security Advisors
  • Main Contributor
  • Core Contributors
  • Contributors
  • Resources
• Sponsorship
• License

Overview

VT Code runs in your terminal and works on your repository: explore, plan, edit, and verify with the model you choose. It owns context, tool calls, and execution policy, so long tasks stay auditable and resumable.

At a glance	What you get
Planning	Plan read-only, then review turn diffs.
Safety	Auditable command policy and sandboxing.
Self-correct	HOVER loop on tool mismatch.
Long runs	Headless exec with compaction and resumption.
Integrations	MCP, Skills, plugins, and editor bridges.
Models	Hosted or local providers per task.

flowchart LR
    H[Hypothesize] --> O[Observe tool evidence]
    O --> V[Verify outcome]
    V --> E[Evaluate vs hypothesis]
    E -->|mismatch| R[Revise and retry corrected]
    R --> H
    E -->|match| D[Done]

Every loop states the expected outcome, gathers bounded evidence, and revises only when the evidence disagrees. See the HOVER acceptance table for the full contract.

Quick start

Requirements: macOS, Linux, or Windows/WSL. Building from source needs Rust 1.98.1+ (edition 2024).

1. Install

# Review the installer script before running it: https://github.com/vinhnx/VTCode/blob/main/scripts/install.sh
curl -fsSL https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.sh | bash

The installer also attempts to add the optional ripgrep and ast-grep search tools. To manage installation yourself, use Homebrew or Cargo:

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

# Or install from crates.io
cargo install vtcode

On Windows, install with PowerShell; Windows artifacts are best-effort and may lag behind macOS/Linux:

irm https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.ps1 | iex

Run vtcode --version to verify the installation. The installation guide covers prerequisites, other install methods, and optional search tools.

2. Configure your project

In your project directory, scaffold the configuration and agent instructions, then add credentials for your provider. For example, to use OpenAI:

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

Replace openai with your provider. vtcode secret add uses secure storage (OS keyring or encrypted file). You can also set credentials in environment variables or a workspace .env file, or use vtcode login if your provider has a supported login flow. See Getting started and Provider guides for provider-specific instructions.

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

[!CAUTION] Keep API keys out of Git and vtcode.toml. If you use a workspace .env file, make sure it is not committed.

3. Run your first task

vtcode   # open the interactive TUI in your project

Ask a focused question, such as "Explain how this project handles authentication," and review proposed changes and test results before committing. For automation and session commands, see Usage; for a guided walkthrough, see the getting started guide.

Usage

Common commands:

Goal	Command
Start the TUI	vtcode
Ask without tools	vtcode ask "explain Rc vs Arc"
Run a task headlessly	vtcode exec "refactor main.rs"
Review pending changes	vtcode review
Schedule recurring work	vtcode schedule create --prompt "..." --every 1h
Resume the last session	vtcode continue
Inspect a run log	vtcode trajectory

Interactive

Use vtcode to explore, plan, and implement changes in the TUI. For larger tasks, start with read-only planning and review the turn diff before committing. /explain then summarizes the outcome, changes, decisions, and verification without another model call; see the explanation options and the interactive guide for controls.

Modes

• ask is tool-free: it prints one reply and exits.
• exec runs the full tool loop. It requires [automation.full_auto] and full_auto workspace trust. Interactive terminals prompt for trust; non-TTY runs need VTCODE_TRUST_WORKSPACE=full-auto. Tool allow-lists, explicit denies, and execution policy still apply.
• review inspects uncommitted changes.

See exec mode and full automation for configuration and output details.

Automation

Recurring work uses 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"

Sessions

Resume or inspect earlier work:

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

Documentation

Guides grouped by task. The full catalog lives in the documentation index, the docs overview, and the Wiki. Integrations are optional; none are required for the quick start.

Get started

• Installation and getting started
• Providers and OAuth login
• FAQ and compatibility

Work in the TUI

• Interactive mode and command reference
• Read-only planning and turn diffs
• Configuration and security model

Automate

• Full automation and decisions probe
• Scheduled tasks and hooks

Extend and integrate

• Skills, plugins, and MCP
• MCP interop for client and server maintainers
• Editors (ACP), WebMCP, and WebMCP deployment
• Companion (experimental) and Memcode

Develop and evaluate

• Development, testing, and evals
• Architecture, HOVER, and protocols
• Loop engineering

Elsewhere: WebMCP app, mirror, and the Memcode write-up.

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]

Build with Rust 1.98.1+ (edition 2024) and install cargo-nextest to run tests. Context handling separates session history from provider request projections; see context architecture and the compaction guide. The architecture guide maps all 23 crates.

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 builds with --locked and RUSTFLAGS="-D warnings"; match locally with RUSTFLAGS="-D warnings" cargo check --locked. Setup and checks are documented in the development overview and the testing guide.

Release binaries and notes: GitHub releases.

Contributing

Contributions are welcome: code, docs, evals, and bug reports (include vtcode trajectory output when possible). Before a PR, read the contribution guide for Conventional Commits, the local gates, and diff expectations.

Maintainers of other MCP servers or MCP clients: VT Code interops on both sides of the protocol (client and server surfaces). See the MCP interop guide for what is implemented, how to register your server, how to point your client at VT Code's read-only search/fetch surface, and how to propose interop fixes.

Security

Report vulnerabilities privately via GitHub private vulnerability reporting; never open a public issue. Details: security policy.

Community

VT Code is created and maintained by Vinh Nguyen with help from the community. You can contribute code, fix docs, or report what broke in a release. You can also fork the repository and adapt it for your own use.

• Report a bug - something looks off? Tell us, and include vtcode trajectory output if you can.
• Request a feature - describe the workflow you wish worked better.
• Ask a question or share feedback - no question is too small.
• Good first issues - friendly, self-contained places to start.
• Help wanted - bigger items where a second pair of hands would genuinely help.
• Contributing guide - setup, checks, and commit conventions.

New to open source or to Rust? That is completely fine. Pick a good first issue or a docs fix, leave a comment, and we will help you scope it and land it. The Code of Conduct keeps review kind and constructive.

Partnerships and private matters: vinhnguyen2308 [at] gmail [dot] com.

Thanks to our contributors

Thank you to everyone below. You are the reason this project keeps moving.

Security Advisors

   

Main Contributor

 

Core Contributors

                 

Contributors

                               

Want to see your avatar here? Every bit counts: a one-line fix, a bug report, or a thoughtful comment. Not sure where to begin? Say hello on a good first issue and we will figure it out together.

Resources

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

Sponsorship

VT Code is maintained in spare time; a sponsorship keeps it independent.

---

   

---

License

First-party code is MIT OR Apache-2.0 under LICENSE. Third-party code keeps its original licenses, listed in THIRD-PARTY-NOTICES.