vtcode 0.146.2

VT Code is an open-source Rust terminal coding agent for interactive and long-running autonomous workflows. It combines OS-native sandboxing, multi-provider LLM support, open protocols, and extensible Skills in one tool.

Features

Runtime and coding

• Agent runtime: interactive TUI, slash commands, streaming, ask/exec CLI, and session resume
• Coding tools: safe file ops, ripgrep search, ast-grep outline symbol maps, fuzzy discovery, code intelligence, project indexing, and terminal execution

Extensibility and providers

• Extensibility: Agent Skills, Model Context Protocol MCP client/server, Agent Plugins portable packages, lifecycle hooks, subagents, custom providers, and Agent Client Protocol (ACP)
• Model providers: 26+ LLM providers including Anthropic, OpenAI, Gemini, Meta AI (Muse), xAI, OpenRouter, Merge Gateway, NVIDIA NIM, local inference via Ollama, LM Studio, and llama.cpp (managed with the /local command), and more

Safety and protocols

• Safety: restricted shell sandbox, tool guardrails, subprocess isolation, full audit logging, and per-workspace approval before lifecycle hooks defined in workspace configuration (vtcode.toml / .vtcode / agent-spec files) can run any shell command
• Provider governance: providers_whitelist restricts which LLM providers VT Code can access, preventing accidental data leakage to unapproved endpoints
• Protocols: Open Responses, Agent2Agent (A2A), ATIF, and Anthropic Messages API

Automation and planning

• Loop engineering: worktree isolation for parallel agents, propose/verify sub-agent separation, durable loop state, and cost guardrails
• Planning workflow: iterate on a build plan with /plan and the plan primary agent, then hand off to build/auto via a structured review gate

Quick start

Install

The native installer is recommended for macOS and Linux. It also installs the ripgrep and ast-grep search tools used by VT Code.

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

Other installation methods are documented in the Installation Guide.

# Homebrew
brew trust vinhnx/tap
brew install vinhnx/tap/vtcode

# Cargo
cargo install vtcode

Initialize a workspace

Run this from the project you want VT Code to work on:

vtcode init

This scaffolds vtcode.toml, .vtcode/, and AGENTS.md.

Configure a provider

Set the API key for the provider you want to use. For example:

export OPENAI_API_KEY="sk-..."

See the provider guides for supported providers, local inference options, and authentication details.

Launch VT Code

vtcode

Common commands

vtcode                         # interactive TUI
vtcode init                    # scaffold project config + AGENTS.md
vtcode ask "explain Rc vs Arc" # one-shot question
vtcode exec "refactor main.rs" # headless task with full tool access
vtcode review                  # review uncommitted changes
vtcode update                  # self-update

Documentation

User guides

• Wiki: community wiki — getting started, configuration, providers, local models, skills, MCP, automation, security, and FAQ
• Installation: installation methods, provider setup, and troubleshooting
• Interactive TUI: primary agents, slash commands (/model, /review, /mcp, /skills, /theme, /compact)
• CLI commands: command reference for interactive, headless, review, and automation workflows
• Full automation: --full-auto CLI, plan-build-evaluate harness, subagents, and scheduled tasks
• Providers: setup guides for all 26+ providers
• Configuration: vtcode.toml, tool config, and lifecycle hooks

Integrations

• Agent Skills: creating, loading, and sharing skills
• Agent Plugins: portable skill + MCP packages via vtcode plugins
• MCP Integration: client and server modes
• Editor guides: Zed ACP, VS Code, and Claude Code

Operations and architecture

• Safety: shell sandbox, security hardening, and threat model
• Protocols: Open Responses, ATIF, A2A, and Anthropic Messages API
• Loop engineering: worktree isolation, propose/verify, loop state, and cost guardrails
• Planning workflow: /plan, review gate, and plan handoff to build/auto agents

Providers

VT Code supports 26+ built-in providers, local inference backends, and custom OpenAI-compatible endpoints.

Provider directory

Additional built-in providers include DeepSeek, xAI, OpenCode Zen, and OpenCode Go.

See the Provider Guides for credentials, model defaults, API capabilities, and setup details. Merge Gateway is a built-in OpenAI-compatible gateway with curated routes and pass-through support for valid explicit provider/model IDs.

Configure a provider

List available providers and configure one from the CLI:

vtcode models list
vtcode models config

For a quick start, set the environment variable documented by your provider. OAuth-based providers can use their dedicated vtcode login command.

Custom providers

Use [[custom_providers]] to add a private gateway, an aggregator such as Atlas Cloud or OmniRoute, or an internal inference cluster:

Basic configuration

[[custom_providers]]
name = "mycorp"
display_name = "MyCorp"
base_url = "https://llm.corp.example/v1"
api_key_env = "MYCORP_API_KEY"
model = "gpt-5-mini"
models = ["gpt-5-mini", "gpt-5.4"]
context_window = 256000   # optional; defaults to 128000 tokens

Set the corresponding environment variable before launching VT Code:

export MYCORP_API_KEY="..."

Capability settings

• context_window: capability size in tokens. It controls UI context sizing, compaction thresholds, and preflight token checks.
• models: optional model IDs to expose in the model picker. model remains the default selection.
• api_format: optional value of auto, openai-chat, openai-responses, or anthropic-messages. Omit it to preserve autodetection, or set it explicitly to prevent fallback to another format.
• Capability defaults include supports_tools, supports_reasoning, supports_reasoning_effort, supports_vision, supports_structured_output, supports_parallel_tool_calls, supports_context_caching, supports_responses_compaction, and supports_context_edits.

The separate context.max_context_tokens setting can impose a lower session budget. See the configuration reference, the custom provider configuration.

Model profiles

Use a profile for model-specific overrides:

[custom_providers.profiles."gpt-5.4"]
api_format = "openai-responses"
context_window = 131072
supports_tools = true
supports_vision = false
supports_structured_output = true

Profiles apply only to an existing model identifier. They do not add models to the picker. Use model or models on the provider entry to control model availability.

Validate the configuration

vtcode models list
vtcode models config
vtcode ask "Summarize this repository"

See the worked provider examples for Atlas Cloud and OmniRoute.

Provider governance

Use providers_whitelist in vtcode.toml to restrict access to approved providers. This helps prevent accidental data leakage in corporate or air-gapped environments.

# vtcode.toml
providers_whitelist = ["opencode-zen", "opencode-go", "gemini"]

Leave it empty, the default, to allow all built-in and custom providers. See the configuration reference and Getting Started for setup instructions.

Local models (experimental)

Run models entirely on your machine for privacy, offline use, or zero token cost. VT Code supports three local backends, all managed from the TUI:

Supported backends

• Ollama (ollama serve), best-supported local backend; auto-loads pulled models.
• LM Studio (lms server start), OpenAI-compatible; select the loaded model in the picker.
• llama.cpp (llama-server -m model.gguf), most automated; auto-starts via LLAMACPP_MODEL_PATH.

TUI commands

/local                 # interactive local server manager
/local start ollama   # start a specific backend
/local troubleshoot   # diagnose connection / model issues

Before each generation VT Code verifies the server is up and the model is loaded, and on failure prints the exact recovery command (e.g. ollama pull gpt-oss:20b) instead of a cryptic error. Local inference is experimental and depends on your hardware. See Local Models guide for trade-offs, hardware sizing, and a reliable-setup checklist. For the full /local reference, see Local Inference Servers.

Development

Build from source

git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh

Workspace layout

Rust stable, edition 2024, MSRV 1.93.0. Workspace of ~30 crates:

Library use

Want to use VT Code as a library? See vtcode-battery-pack for a curated set of crates you can add to your own Rust projects.

Quality checks

./scripts/check-dev.sh  # fast quality gate (clippy, fmt, check)
cargo nextest run        # parallel test runner

Read more about Rust Cargo Battery Pack in the blog.

Contributing

VT Code is built by an open source community. Whether you're fixing bugs, improving docs, proposing features, reporting security issues, or shipping patches, all contributions are welcome.

Ways to contribute

• Security advisories: Responsible disclosure makes everyone safer. See the Security Policy for reporting guidelines.
• Bug fixes and patches: Small or large, every fix matters.
• Documentation: Guides, examples, and improvements help the whole ecosystem.
• Features and ideas: Open an issue or start a discussion.
• Code reviews and testing: Help keep the project healthy.

Getting started

• Browse good first issues
• Read CONTRIBUTING.md for humans
• Check AGENTS.md for AI agents

Contributors

Thank you to everyone who has contributed to VT Code, your work makes this project better for all of us.

Support

Sponsorship

VT Code is a labor of love built in my spare time. If it's helped you ship something or learn something, a sponsorship would mean the world.

License

First-party code is licensed under MIT OR Apache-2.0, choose whichever works best for you. See LICENSE for the full Apache-2.0 text; MIT terms are also granted under the same copyright.

Third-party and inspired-by code remains under its original licenses. See THIRD-PARTY-NOTICES for attributions.