<p align="center">
<img src="./resources/logo/vt_code_adaptive.svg" alt="VT Code" style="border-radius: 12px" />
</p>
<p align="center">
<a href="./docs/skills/SKILLS_GUIDE.md"><img src="https://img.shields.io/badge/Agent%20Skills-BFB38F?style=flat-square" alt="Skills" /></a>
<a href="./docs/guides/zed-acp.md"><img src="https://img.shields.io/badge/ACP-Zed-383B73?style=flat-square&logo=zedindustries" alt="Zed ACP" /></a>
<a href="./docs/guides/mcp-integration.md"><img src="https://img.shields.io/badge/MCP-A63333?style=flat-square&logo=modelcontextprotocol" alt="MCP" /></a>
</p>
<p align="center">
<a href="https://github.com/vinhnx/VTCode/actions/workflows/build-linux-windows.yml"><img src="https://github.com/vinhnx/VTCode/actions/workflows/build-linux-windows.yml/badge.svg" alt="Build Linux and Windows Binaries"></a>
<a href="https://ratatui.rs/highlights/v030/"><img src="https://img.shields.io/badge/Built_With-Ratatui-000?logo=ratatui&logoColor=fff&labelColor=000&color=fff" alt="Built with Ratatui" /></a>
<a href="https://deepwiki.com/vinhnx/VTCode"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" /></a>
</p>
<p align="center">
<img src="./resources/gif/vtcode.gif" alt="VT Code demo" width="40%" style="border-radius: 10px" /> <img src="./resources/screenshots/vtcode-01237.png" alt="VT Code screenshot" width="46%" style="border-radius: 10px" />
<br><em>Secure, open, universal.</em>
</p>
## What is VT Code?
VT Code is a Rust coding agent built for long-running autonomous workflows. It has OS-native sandboxing, multi-provider LLM support, open protocols, and extensible Skills.
## Features
- **Agent runtime**: interactive TUI, slash commands, streaming, `ask`/`exec` CLI, and session resume
- **Coding tools**: safe file ops, [ripgrep](https://github.com/BurntSushi/ripgrep) search, [ast-grep](https://ast-grep.github.io/) outline symbol maps, fuzzy discovery, code intelligence, project indexing, and terminal execution
- **Extensibility**: [Agent Skills](https://agentskills.io), [Model Context Protocol](https://modelcontextprotocol.io/) MCP client/server, lifecycle hooks, subagents, custom providers, and [Agent Client Protocol](https://agentclientprotocol.com) (ACP)
- **Model providers**: 21+ LLM providers including Anthropic, OpenAI, Gemini, OpenRouter, **local inference via Ollama, LM Studio, and llama.cpp** (managed with the `/local` command), and more
- **Safety**: restricted shell sandbox, tool guardrails, subprocess isolation, and full audit logging
- **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
- **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 via homebrew
```yaml
brew install vinhnx/tap/vtcode
```
One-liner for macOS/Linux (also installs ripgrep + ast-grep)
```yaml
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
```
Scaffolds `vtcode.toml`, `.vtcode/`, and `AGENTS.md` in your project
```yaml
vtcode init
```
Launch VT Code
```yaml
vtcode
```
### Common commands
```yaml
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
- [**Interactive TUI**](./docs/user-guide/interactive-mode.md): primary agents, slash commands (`/model`, `/review`, `/mcp`, `/skills`, `/theme`, `/compact`)
- [**Full automation**](./docs/guides/full-automation.md): `--full-auto` CLI, plan-build-evaluate harness, subagents, and scheduled tasks
- [**Providers**](./docs/providers/PROVIDER_GUIDES.md): setup guides for all 21 providers
- [**Configuration**](./docs/config/CONFIG_FIELD_REFERENCE.md): `vtcode.toml`, tool config, and lifecycle hooks
- [**Agent Skills**](./docs/skills/SKILLS_GUIDE.md): creating, loading, and sharing skills
- [**MCP Integration**](./docs/guides/mcp-integration.md): client and server modes
- [**Editor guides**](./docs/guides/zed-acp.md): Zed ACP, VS Code, and Claude Code
- [**Safety**](./docs/security/SECURITY_MODEL.md): shell sandbox, security hardening, and threat model
- [**Protocols**](./docs/protocols/OPEN_RESPONSES.md): Open Responses, ATIF, A2A, and Anthropic Messages API
- [**Loop engineering**](./docs/project/PLAN-loop-engineering.md): worktree isolation, propose/verify, loop state, and cost guardrails
- [**Planning workflow**](./docs/guides/planning-workflow.md): `/plan`, review gate, and plan handoff to build/auto agents
## Providers
VT Code supports 21+ LLM providers out of the box, plus any OpenAI-compatible API via `[[custom_providers]]`.
| Category | Providers |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cloud LLMs** | [Anthropic](./docs/providers/PROVIDER_GUIDES.md#anthropic-claude) · [OpenAI](./docs/providers/PROVIDER_GUIDES.md#openai-gpt) · [Gemini](./docs/providers/PROVIDER_GUIDES.md#google-gemini) · [Z.AI](./docs/providers/PROVIDER_GUIDES.md#zai-zai) · [Moonshot (Kimi)](./docs/providers/PROVIDER_GUIDES.md#moonshot-kimi) · [StepFun](./docs/providers/PROVIDER_GUIDES.md#stepfun) · [MiniMax](./docs/providers/PROVIDER_GUIDES.md#minimax) · [Mistral](./docs/providers/PROVIDER_GUIDES.md#mistral) · [Qwen](./docs/providers/PROVIDER_GUIDES.md#qwen) |
| **Gateways** | [OpenRouter](./docs/providers/PROVIDER_GUIDES.md#openrouter-marketplace) · [Evolink](./docs/providers/PROVIDER_GUIDES.md#evolink-multi-model-gateway) · [HuggingFace](./docs/providers/PROVIDER_GUIDES.md#huggingface) · [Atlas Cloud](./docs/providers/PROVIDER_GUIDES.md#atlas-cloud) |
| **Local inference** | [Ollama](./docs/providers/PROVIDER_GUIDES.md#ollama-local--cloud-models) · [LM Studio](./docs/providers/PROVIDER_GUIDES.md#lm-studio-local-server) · [llama.cpp](./docs/providers/PROVIDER_GUIDES.md#llamacpp-local-server) |
| **Other** | [GitHub Copilot](./docs/providers/PROVIDER_GUIDES.md#github-copilot) · [Anthropic API Compat](./docs/providers/PROVIDER_GUIDES.md#anthropic-api-compatibility-server) · [Poolside](./docs/providers/PROVIDER_GUIDES.md#poolside) |
Read: [Provider Guides](./docs/providers/PROVIDER_GUIDES.md).
### Provider governance
Use `providers_whitelist` in `vtcode.toml` to restrict which LLM providers VT Code may access. This prevents accidental data leakage to unapproved endpoints in corporate or air-gapped environments.
```toml
# vtcode.toml
providers_whitelist = ["opencode-zen", "opencode-go", "gemini"]
```
Leave it empty (the default) to allow all built-in and custom providers. See [Configuration](./docs/config/CONFIG_FIELD_REFERENCE.md) and [Getting Started](./docs/user-guide/getting-started.md) for full 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:
- **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`.
```yaml
/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](./docs/guides/local-models.md) for trade-offs, hardware
sizing, and a reliable-setup checklist. For the full `/local` reference, see
[Local Inference Servers](./docs/providers/local-servers.md).
## Development
```yaml
git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh
```
Rust stable, edition 2024, MSRV 1.93.0. Workspace of ~30 crates:
| Layer | Crates |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Binary | `vtcode` |
| Common | `vtcode-commons`, `vtcode-exec-events`, `vtcode-macros`, `vtcode-utility-tool-specs` |
| Codegen | `vtcode-core`, `vtcode-ui`, `vtcode-config`, `vtcode-llm`, `vtcode-skills`, `vtcode-safety`, `vtcode-a2a`, `vtcode-mcp`, `vtcode-auth`, `vtcode-acp`, `vtcode-indexer`, `vtcode-bash-runner`, `vtcode-memory`, `vtcode-eval` |
Want to use VT Code as a library? See [`vtcode-battery-pack`](https://github.com/vinhnx/vtcode-battery-pack) for a curated set of crates you can add to your own Rust projects.
```yaml
./scripts/check-dev.sh # fast quality gate (clippy, fmt, check)
cargo nextest run # parallel test runner
```
## Contributing