Terminal-first. Desktop-ready.
Explore, plan, edit, and verify; all with the model you choose.
Desktop app · watch the demo video
Terminal TUI · One-shot ask
VT Code works on your repository from the terminal or its native macOS app. 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. |
Requirements: macOS, Linux, or Windows/WSL. Building from source needs Rust 1.99.1+ (edition 2024).
# 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 | bashTo manage installation yourself, use Homebrew or Cargo:
brew trust vinhnx/tap
brew install vinhnx/tap/vtcode
# Or install from crates.io
cargo install vtcodeOn Windows, install with PowerShell (artifacts are best-effort and may lag behind macOS/Linux):
irm https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.ps1 | iexRun vtcode --version to verify the installation. The installation guide
covers prerequisites, other install methods, desktop flags, and optional search tools.
In your project directory, scaffold the configuration and add credentials for your provider:
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 storageReplace openai with your provider. Keys use secure storage (OS keyring or encrypted file); alternatives include
environment variables, a workspace .env file, or vtcode login where supported. See
Getting started and Provider guides.
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
copilotCLI. See OAuth authentication.Caution: Keep API keys out of Git and
vtcode.toml; never commit a workspace.envfile.
vtcode # open the interactive TUI in your projectAsk a focused question, review proposed changes and test results before committing, and see Usage for automation and session commands.
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 |
Use vtcode to explore, plan, and implement changes in the TUI. For larger tasks, begin with
read-only planning, then review the
turn diff before committing. Run /explain to summarize the outcome
without another model call; see the interactive guide for controls.
askis tool-free: it prints one reply and exits.execruns the full tool loop. It requires[automation.full_auto]andfull_autoworkspace trust. Interactive terminals prompt for trust; non-TTY runs needVTCODE_TRUST_WORKSPACE=full-auto. Tool allow-lists, explicit denies, and execution policy still apply.reviewinspects uncommitted changes.
Recurring work uses scheduled tasks, durable prompt jobs on the same exec
runtime. Resume or fork earlier work with vtcode continue (or --session-id <id>), continue a headless run with
vtcode exec resume --last, and inspect logs with vtcode trajectory. See exec mode
and full automation for configuration details.
The GUI talks to a matching local service binary while the unified runloop still owns providers, tool policy,
sandboxing, and sessions. Desktop reuses your CLI configuration, provider credentials, workspace trust, and sandbox
policy. Configure a provider from Terminal first, for example with vtcode secret add openai.
On Apple Silicon, download the app from the latest release or
install it with vtcode desktop --install. Intel Macs can build the app from source. Launch an installed app with
vtcode desktop. See the
desktop workspace guide for system requirements, source builds,
Gatekeeper approval, and troubleshooting.
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.
- Installation and getting started
- Desktop app for the native macOS GUI
- Providers and OAuth login
- FAQ and compatibility
- Interactive mode and command reference
- Read-only planning and turn diffs
- Configuration and security model
- Skills, plugins, and MCP
- MCP interop for client and server maintainers
- Editors (ACP), WebMCP, and WebMCP deployment
- Companion (experimental) and Memcode
- Development, testing, and evals
- Architecture, HOVER, and protocols
- Loop engineering
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.99.1+ (edition 2024) and install cargo-nextest to run tests. The
architecture guide maps all 25 crates, including the context and compaction design.
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.
Contributions are welcome: code, docs, evals, and bug reports (include vtcode trajectory
output when possible). Before a PR, read the contribution guide. MCP maintainers: see the
interop guide for client and server integration.
Report vulnerabilities privately via GitHub private vulnerability reporting; never open a public issue. Details: security policy.
- Report a bug - something looks off? Tell us,
and include
vtcode trajectoryoutput 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 Rust? Pick a good first issue or docs fix and we will help scope 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.
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.
- Building VT Code, a year in: harness design, evals, security, and lessons learned.
- Podcast · Video
First-party code is MIT OR Apache-2.0, available under either LICENSE-MIT or LICENSE (Apache-2.0). Third-party code keeps its original licenses, listed in THIRD-PARTY-NOTICES.
