VT Code is an open-source terminal coding agent that lets you plan, build, and review code using hosted or local AI models.
Use the interactive TUI or vtcode exec to explore a codebase, plan and review changes, and run tools. Choose a model and permission level; VT Code manages context, tool calls, and execution policy, with resumable sessions, sandboxed tools, Model Context Protocol (MCP) support, and Agent Client Protocol (ACP) integration for editors.
README
Terminal-first. Desktop-ready.
Explore, plan, edit, and verify; all with the model you choose.
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.
Run vtcode --version to verify the installation. The installation guide
covers prerequisites, other install methods, desktop flags, and optional search tools.
2. Configure your project
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 storage
Replace 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 copilot CLI. See
> OAuth authentication.
>
> Caution: Keep API keys out of Git and vtcode.toml; never commit a workspace .env file.
3. Run your first task
vtcode # open the interactive TUI in your project
Ask a focused question, review proposed changes and test results before committing, and see Usage for
automation and session commands.
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
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.
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.
Recurring work uses scheduled tasks, durable prompt jobs on the same exec
runtime. Resume or fork earlier work with vtcode continue (or --session-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.
Desktop app
The full VT Code engine in a native Mac app
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.
Install (macOS 15+)
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.
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.
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.
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.
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.
Thanks to our contributors
Thank you to everyone below. You are the reason this project keeps moving.
View all contributors (30)
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.
Special thanks to current sponsors: Codemod and CodeRabbit for ongoing support.
Thank you
License
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.
Terminal TUI · One-shot ask
