VT Code

An open-source coding agent for your terminal.

Plan, build, and review with hosted or local models, sandboxed tools, and resumable sessions.

Contents

• Overview
• Quick start
• Usage
• Documentation
• Development
• Contributing
• Security
• Community and support
• 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]

Loading

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://github.com/raw/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.

Headless

ask is tool-free, exec runs the full tool loop, and review inspects uncommitted changes:

vtcode ask "explain Rc vs Arc"
vtcode exec "refactor main.rs"
vtcode review

Automation

exec runs the full tool loop and requires [automation.full_auto] plus full_auto workspace trust. Interactive terminals prompt for trust. Non-TTY runs require VTCODE_TRUST_WORKSPACE=full-auto; tool allow-lists, explicit denies, and execution policy still apply. See exec mode and full automation for configuration and output details.

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.

Goal	Guides
Get started	Installation · Getting started · Providers · OAuth login · FAQ · Compatibility
Work in the TUI	TUI · Command reference · Planning · Turn diffs · Configuration · Safety
Automate	Full automation · Decisions probe · Scheduled tasks · Hooks
Extend and integrate	Skills · Plugins · MCP · Editors (ACP) · WebMCP · Companion (experimental) · Memcode · WebMCP deployment
Develop and evaluate	Development · Testing · Evals · Architecture · HOVER · Protocols · Loop engineering

Elsewhere: WebMCP app · mirror · 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]

Loading

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.

Security

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

Community and support

VT Code is created and maintained by @vinhnx, with help from everyone in the grid below. Whether you write code, fix docs, or just try a release and tell me what broke, you are welcome here.

• Report a bug - something looks off? Tell me, 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 I 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.

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

View all contributors (28)

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

Share VT Code

If VT Code helped you ship something, spread the word:

• 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 under LICENSE. Third-party code keeps its original licenses, listed in THIRD-PARTY-NOTICES.