vtcode

On Windows (best-effort artifacts; may lag behind macOS/Linux):

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

Verify with vtcode --version. The installation guide covers other install methods, desktop flags, and optional search tools.

2. Configure your project

In your project directory, scaffold configuration and add credentials:

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 are environment variables, a workspace .env file, or vtcode login where supported. See getting started and the provider guides for provider-specific setup.

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, then review proposed changes and test results before committing. See Usage for automation and session commands.

Usage

Common commands (see the command reference):

For larger tasks, start read-only, review the turn diff before committing, and use /explain for a summary without another model call. See the interactive guide.

Modes

• ask is tool-free: it prints one reply and exits.
• exec runs the full tool loop under explicit workspace trust (full_auto plus [automation.full_auto]). Terminals prompt for trust; non-TTY runs need VTCODE_TRUST_WORKSPACE=full-auto. Allow-lists, denies, and execution policy still apply.
• review inspects uncommitted changes.

Schedule recurring work on the same exec runtime. Resume or fork with vtcode continue (or --session-id <id>), resume headless runs with vtcode exec resume --last, and inspect logs with vtcode trajectory. See exec mode and full automation.

Desktop app

The native macOS app shares the CLI runloop, providers, tool policy, sandboxing, sessions, configuration, and credentials. Configure a provider first (see Quick start).

Install (macOS 15+)

On Apple Silicon, install it with Homebrew (update with brew upgrade --cask vinhnx/tap/vtcode-desktop):

brew install --cask vinhnx/tap/vtcode-desktop

Without Homebrew, download it from the latest release or run vtcode desktop --install. Launch it with vtcode desktop or from Finder. Intel Macs build from source.

[!WARNING] First launch needs a one-time macOS security approval. Builds are ad hoc signed, not notarized, so macOS blocks the first launch (Homebrew cask installs included). Open the app once, click Open Anyway in System Settings › Privacy & Security, then open it again. The button shows for about an hour after a block.

See the desktop workspace guide for requirements, source builds, and troubleshooting.

Documentation

Start from the documentation index or Wiki; integrations below are optional.

Get started

• Installation and getting started
• Desktop app for the native macOS GUI
• 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, MCP
• MCP interop for client and server maintainers
• Editors (ACP), WebMCP (deployment), Companion, and Memcode

Develop and evaluate

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

Development

graph LR
    BIN[vtcode binary] --> CORE[vtcode-core harness]
    CORE --> LLM[vtcode-llm]
    CORE --> SAFETY[vtcode-safety]
    CORE --> EVENTS[vtcode-exec-events]
    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. See the development overview and testing guide.

Release binaries and notes live on GitHub releases.

Contributing

Contributions are welcome: code, docs, evals, and bug reports (include vtcode trajectory output). Read the contribution guide before opening a PR; MCP maintainers should also see the interop guide.

Security

Report vulnerabilities privately with GitHub private vulnerability reporting. See the security policy.

Community

• Report a bug · Request a feature · Discussions
• Good first issues · Help wanted

The Code of Conduct keeps review constructive. Contact: 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.

Resources

• Building VT Code, a year in · Podcast · Video

Support VT Code

Thanks to current sponsors: Codemod and CodeRabbit.

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.