<p align="center">
<img src="./resources/logo/vt_code_adaptive.svg" alt="VT Code" style="border-radius: 12px" width="300"/>
</p>
<p align="center">
<a href="https://agentskills.io/"><img src="https://img.shields.io/badge/Agent%20Skills-BFB38F?style=flat-square&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTYgMC41TDI5LjQyMzQgOC4yNVYyMy43NUwxNiAzMS41TDIuNTc2NjEgMjMuNzVWOC4yNUwxNiAwLjVaIiBmaWxsPSIjZmZmZmZmIi8%2BPC9zdmc%2B&logoColor=white" alt="Agent Skills" /></a>
<a href="./docs/guides/zed-acp.md"><img src="https://img.shields.io/badge/Agent Client Protocol-383B73?style=flat-square&logo=zedindustries" alt="Agent Client Protocol" /></a>
<a href="./docs/guides/mcp-integration.md"><img src="https://img.shields.io/badge/Model Context Protocol-A63333?style=flat-square&logo=modelcontextprotocol" alt="Model Context Protocol" /></a>
<a href="./docs/guides/agent-plugins.md"><img src="https://img.shields.io/badge/Agent%20Plugins-5865F2?style=flat-square&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTgiIGhlaWdodD0iMTciIHZpZXdCb3g9IjAgMCAxOCAxNyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8c3R5bGU%2BCiAgICBwYXRoIHsgZmlsbDogI2ZmZjsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgeyBwYXRoIHsgZmlsbDogI2ZmZjsgfSB9CiAgPC9zdHlsZT4KICA8cGF0aCBkPSJNMi44OTUwMiAxMi43NjA3VjEzLjg5ODRMMy41NjAwNiAxNC41MzgxSDE0LjQzOTlMMTUuMTA0IDEzLjg5OTRWMTIuNzYwN0gxNi43NDE3VjE0LjU5NjdMMTUuMzM2NCAxNS45NDczTDE1LjA5ODEgMTYuMTc1OEgyLjkwMDg4TDIuNjYzNTcgMTUuOTQ3M0wxLjUwOTI4IDE0LjgzODlMMS4yNTgzIDE0LjU5NjdWMTIuNzYwN0gyLjg5NTAyWk0xNS4wOTgxIDBMMTUuMzM2NCAwLjIyODUxNkwxNi40ODk3IDEuMzM2OTFMMTYuNzQxNyAxLjU3ODEyVjMuNDE0MDZIMTUuMTA0VjIuMjc1MzlMMTQuNDM5IDEuNjM2NzJIMy41NjAwNkwyLjg5NTAyIDIuMjc1MzlWMy40MTQwNkgxLjI1ODNWMS41NzgxMkwyLjY2MzU3IDAuMjI4NTE2TDIuOTAwODggMEgxNS4wOTgxWiIvPgogIDxwYXRoIGQ9Ik0xNi4zNjI4IDguMTIwMzZDMTYuMzYyOCA3LjI0Mjc3IDE1LjY1MTUgNi41MzE1NyAxNC43NzM5IDYuNTMxNDlDMTMuODk2MyA2LjUzMTQ5IDEzLjE4NTEgNy4yNDI3MiAxMy4xODUxIDguMTIwMzZDMTMuMTg1MSA4Ljk5NzkzIDEzLjg5NjMgOS43MDkyMyAxNC43NzM5IDkuNzA5MjNWMTEuMzQ2OUwxNC42MDc5IDExLjM0MkMxMi45NTgxIDExLjI1ODUgMTEuNjM1IDkuOTM2MTIgMTEuNTUxMyA4LjI4NjM4TDExLjU0NzQgOC4xMjAzNkMxMS41NDc0IDYuMzM4NDYgMTIuOTkyIDQuODkzOCAxNC43NzM5IDQuODkzOEwxNC45Mzk5IDQuODk3NzFDMTYuNjQ0NiA0Ljk4NDE4IDE4LjAwMDUgNi4zOTQxOSAxOC4wMDA1IDguMTIwMzZMMTcuOTk1NiA4LjI4NjM4QzE3LjkwOTEgOS45OTEgMTYuNSAxMS4zNDY4IDE0Ljc3MzkgMTEuMzQ2OVY5LjcwOTIzQzE1LjY1MTQgOS43MDkxNSAxNi4zNjI3IDguOTk3ODggMTYuMzYyOCA4LjEyMDM2WiIvPgogIDxwYXRoIGQ9Ik02LjQ1MjgzIDguMTIwMjFDNi40NTI4MyA5LjkwMjExIDUuMDA4MzEgMTEuMzQ2NiAzLjIyNjQxIDExLjM0NjZDMS40NDQ1MSAxMS4zNDY2IDAgOS45MDIxMSAwIDguMTIwMjFDMCA2LjMzODMxIDEuNDQ0NTEgNC44OTM4IDMuMjI2NDEgNC44OTM4QzUuMDA4MzEgNC44OTM4IDYuNDUyODMgNi4zMzgzMSA2LjQ1MjgzIDguMTIwMjFaIi8%2BCiAgPHBhdGggZD0iTTUuMTQyNTggOC4xMjAzNkM1LjE0MjU4IDcuMDYyMjUgNC4yODQ2NiA2LjIwNDQzIDMuMjI2NTYgNi4yMDQzNUMyLjE2ODQgNi4yMDQzNSAxLjMxMDU1IDcuMDYyMiAxLjMxMDU1IDguMTIwMzZDMS4zMTA2MyA5LjE3ODQ2IDIuMTY4NDUgMTAuMDM2NCAzLjIyNjU2IDEwLjAzNjRWMTEuMzQ2OUwzLjA2MDU1IDExLjM0MkMxLjQxMDc3IDExLjI1ODUgMC4wODc1OTIgOS45MzYxMiAwLjAwMzkwNjI1IDguMjg2MzhMMCA4LjEyMDM2QzAgNi4zMzg0NiAxLjQ0NDY2IDQuODkzOCAzLjIyNjU2IDQuODkzOEwzLjM5MjU4IDQuODk3NzFDNS4wOTcyNiA0Ljk4NDE4IDYuNDUzMTIgNi4zOTQxOSA2LjQ1MzEyIDguMTIwMzZMNi40NDgyNCA4LjI4NjM4QzYuMzYxNzUgOS45OTEgNC45NTI2NiAxMS4zNDY4IDMuMjI2NTYgMTEuMzQ2OVYxMC4wMzY0QzQuMjg0NjEgMTAuMDM2MyA1LjE0MjUgOS4xNzg0MSA1LjE0MjU4IDguMTIwMzZaIi8%2BCiAgPHBhdGggZD0iTTEwLjM4NCA3LjMxNTE5TDEwLjM4NCA4Ljk1Mjg4TDQuODQ1OTUgOC45NTI4OEw0Ljg0NTk1IDcuMzE1MTlMMTAuMzg0IDcuMzE1MTlaIi8%2BCjwvc3ZnPgo%3D&logoColor=white" alt="Agent Plugins" /></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>
## Contents
- [Overview](#overview)
- [Why VT Code](#why-vt-code)
- [Quick start](#quick-start)
- [Documentation](#documentation)
- [Providers](#providers)
- [Development](#development)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)
> New here? Start with [Installation](./docs/installation/README.md), then
> [Getting Started](./docs/user-guide/getting-started.md).
## Overview
<p align="center">
<img src="./resources/gif/vtcode.gif" alt="VT Code demo" width="60%" style="border-radius: 10px" />
<br><em>Secure, open, universal.</em>
</p>
VT Code is an open-source Rust terminal coding agent for interactive and
long-running autonomous work. A responsive TUI, safe tools, multi-provider LLM
support, open protocols, and extensible Skills take you from question to
reviewed change without leaving the terminal.
> **Status:** Active development. Local inference and some automation flows are
> experimental and may change between releases.
>
> **Behind the build:** [Building VT Code, a year in](https://huggingface.co/blog/vinhnx90/building-vtcode-a-year-in):
> harness design, evals, security, and lessons from a year of building.
## Why VT Code
- **Harness, not a wrapper**: the model reasons; the harness enforces progress
with tools, sandbox, evals, and state.
- **Safety-first**: sandboxed shell, command policies, per-workspace approvals,
and fail-closed handling of injection, path/symlink escape, and env leakage.
- **Built for long runs**: durable session memory, spooled output,
auto-compaction, and verification before "done".
- **Protocol-native**: MCP, Skills, Agent Plugins, ACP (Zed), A2A, and ATIF
export with no core forks.
- **Parallel by design**: worktree isolation, propose/verify sub-agents,
`/plan` workflow, and cost guardrails.
- **Runs anywhere**: 30 providers plus local Ollama, LM Studio, and llama.cpp.
## Quick start
```bash
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# or: brew install vinhnx/tap/vtcode | cargo install vtcode
cd path/to/your/project
vtcode init # scaffolds config + AGENTS.md; review before committing
export OPENAI_API_KEY="sk-..." # or `vtcode login` for OAuth providers
vtcode # interactive TUI
```
```bash
vtcode ask "explain Rc vs Arc" # one-shot question
vtcode exec "refactor main.rs" # headless task
vtcode review # review uncommitted changes
```
See [Installation](./docs/installation/README.md) and
[Getting Started](./docs/user-guide/getting-started.md). Never commit API keys
or put them in `vtcode.toml`.
### WebMCP browser bridge (opt-in)
Pair a running session from the TUI (`/webmcp pair <origin>`) or serve a
bounded workspace (`vtcode webmcp serve --origin <origin> --allowed-root <dir>`).
Hosted app: <https://vtcode.vinhnx.chatgpt.site/> · fallback:
<https://vinhnx.github.io/VTCode/>. Details: [user guide](./docs/user-guide/webmcp.md),
[deployment reference](./docs/reference/webmcp.md).
## Documentation
- **Start**: [Installation](./docs/installation/README.md) ·
[Getting started](./docs/user-guide/getting-started.md) ·
[Wiki](https://github.com/vinhnx/VTCode/wiki) ·
[Blog: Building VT Code, a year in](https://huggingface.co/blog/vinhnx90/building-vtcode-a-year-in)
- **Use**: [TUI](./docs/user-guide/interactive-mode.md) ·
[CLI](./docs/user-guide/commands.md) · [WebMCP](./docs/user-guide/webmcp.md) ·
[Automation](./docs/guides/full-automation.md) · [Planning](./docs/guides/planning-workflow.md) ·
[Configuration](./docs/config/CONFIG_FIELD_REFERENCE.md)
- **Extend**: [Skills](./docs/skills/SKILLS_GUIDE.md) ·
[Plugins](./docs/guides/agent-plugins.md) · [MCP](./docs/guides/mcp-integration.md) ·
[Editors](./docs/guides/zed-acp.md)
- **Operate**: [Safety](./docs/security/SECURITY_MODEL.md) ·
[Protocols](./docs/protocols/OPEN_RESPONSES.md) ·
[Loop engineering](./docs/project/PLAN-loop-engineering.md) ·
[Architecture](./docs/ARCHITECTURE.md)
## Providers
30 built-in providers, custom OpenAI-compatible endpoints, and local backends.
[Provider Guides](./docs/providers/PROVIDER_GUIDES.md) is the source of truth
for credentials and model defaults.
```bash
vtcode models list
vtcode models config
```
Restrict providers per workspace with `providers_whitelist` in `vtcode.toml`.
Local inference (experimental) via Ollama, LM Studio, and llama.cpp, managed
with `/local` in the TUI: see [Local Models](./docs/guides/local-models.md).
## Development
```bash
git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh
./scripts/check-dev.sh # fast gate: clippy, fmt, check
cargo nextest run # tests (never `cargo test`)
```
Rust stable, edition 2024. ~30 crates layered as
`types → config → core → tools → agent → TUI`, with `ThreadEvent` as the
authoritative runtime contract. See [Development setup](./docs/development/DEVELOPMENT_SETUP.md)
and [Testing](./docs/development/testing.md).
## Contributing
VT Code grows with its community. Bug fixes, docs, ideas, testing, and
reviews are all welcome.
### Ways to contribute
- **Security advisories**: Please report vulnerabilities privately first: [Security Policy](https://github.com/vinhnx/VTCode/security/policy).
- **Bug fixes and patches**: Small or large, every fix counts.
- **Documentation**: Guides, examples, and corrections help everyone.
- **Features and ideas**: Open an issue or start a discussion.
- **Code reviews and testing**: Trying things out and reporting breakage keeps the project healthy.
### Getting started
- Browse [good first issues](https://github.com/vinhnx/vtcode/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
- Read [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for humans
- Check [AGENTS.md](./AGENTS.md) for AI agents
Small, focused PRs merge fastest. If you get stuck, open an issue for help.
### Contributors
Thank you to everyone who shaped VT Code.
<p align="center">
<a href="https://github.com/kernitus"><img src="https://avatars.githubusercontent.com/u/2789734?s=60" width="40" height="40" alt="@kernitus" title="@kernitus 👑 Main Contributor (52 commits)" style="border-radius: 50%; border: 2px solid #FFD700;" /></a>
<a href="https://github.com/7jrxt42BxFZo4iAnN4CX"><img src="https://avatars.githubusercontent.com/u/72938937?s=60" width="40" height="40" alt="@7jrxt42BxFZo4iAnN4CX" title="@7jrxt42BxFZo4iAnN4CX 🚀 Core contributor (40 commits) - subagents, hooks, config & TUI fixes (#737, #738, #740-#742+)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/oiwn"><img src="https://avatars.githubusercontent.com/u/398035?s=60" width="40" height="40" alt="@oiwn" title="@oiwn 🚀 Core contributor (6 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/Sachin-Bhat"><img src="https://avatars.githubusercontent.com/u/25080916?s=60" width="40" height="40" alt="@Sachin-Bhat" title="@Sachin-Bhat 🚀 Core contributor (3 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/chenrui333"><img src="https://avatars.githubusercontent.com/u/1580956?s=60" width="40" height="40" alt="@chenrui333" title="@chenrui333 🚀 Core contributor (3 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/gzsombor"><img src="https://avatars.githubusercontent.com/u/66230?s=60" width="40" height="40" alt="@gzsombor" title="@gzsombor 🚀 Core contributor (2 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/leonj1"><img src="https://avatars.githubusercontent.com/u/5171829?s=60" width="40" height="40" alt="@leonj1" title="@leonj1 🚀 Core contributor (2 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/netbrah"><img src="https://avatars.githubusercontent.com/u/162479981?s=60" width="40" height="40" alt="@netbrah" title="@netbrah 🚀 Core contributor (2 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/xcrong"><img src="https://avatars.githubusercontent.com/u/46434477?s=60" width="40" height="40" alt="@xcrong" title="@xcrong 🚀 Core contributor (2 commits)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/lucaszhu-hue"><img src="https://avatars.githubusercontent.com/u/278269343?s=60" width="40" height="40" alt="@lucaszhu-hue" title="@lucaszhu-hue 🚀 Core contributor (2 commits) - Atlas Cloud (#648, #662)" style="border-radius: 50%; border: 2px solid #50C878;" /></a>
<a href="https://github.com/raphamorim"><img src="https://avatars.githubusercontent.com/u/3630346?s=60" width="40" height="40" alt="@raphamorim" title="@raphamorim 💡 PR #708, rio-vt migration (1 commit)" style="border-radius: 50%; border: 2px solid #4A90D9;" /></a>
<a href="https://github.com/nnfrog"><img src="https://avatars.githubusercontent.com/u/142202920?s=60" width="40" height="40" alt="@nnfrog" title="@nnfrog 🛡️ GHSA-r249-hpfx-x2w7 (security advisory)" style="border-radius: 50%; border: 2px solid #FF6B6B;" /></a>
<a href="https://github.com/glmgbj233"><img src="https://avatars.githubusercontent.com/u/115564047?s=60" width="40" height="40" alt="@glmgbj233" title="@glmgbj233 🛡️ GHSA-wqgw-crr5-cr2p (security advisory)" style="border-radius: 50%; border: 2px solid #FF6B6B;" /></a>
<a href="https://github.com/EvoLinkAI"><img src="https://avatars.githubusercontent.com/u/253253881?s=60" width="40" height="40" alt="@EvoLinkAI" title="@EvoLinkAI ✨ Contributor (1 commit) - Evolink provider (#664)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/diegosouzapw"><img src="https://avatars.githubusercontent.com/u/8016841?s=60" width="40" height="40" alt="@diegosouzapw" title="@diegosouzapw ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/ForrestThump"><img src="https://avatars.githubusercontent.com/u/44280834?s=60" width="40" height="40" alt="@ForrestThump" title="@ForrestThump ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/morler"><img src="https://avatars.githubusercontent.com/u/478444?s=60" width="40" height="40" alt="@morler" title="@morler ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/poelzi"><img src="https://avatars.githubusercontent.com/u/66107?s=60" width="40" height="40" alt="@poelzi" title="@poelzi ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/RobertBorg"><img src="https://avatars.githubusercontent.com/u/1288566?s=60" width="40" height="40" alt="@RobertBorg" title="@RobertBorg ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/Sanjays2402"><img src="https://avatars.githubusercontent.com/u/51058514?s=60" width="40" height="40" alt="@Sanjays2402" title="@Sanjays2402 ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/TuanLe-bk18"><img src="https://avatars.githubusercontent.com/u/222461688?s=60" width="40" height="40" alt="@TuanLe-bk18" title="@TuanLe-bk18 ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
<a href="https://github.com/uiYzzi"><img src="https://avatars.githubusercontent.com/u/40852301?s=60" width="40" height="40" alt="@uiYzzi" title="@uiYzzi ✨ Contributor (1 commit)" style="border-radius: 50%; border: 2px solid #B19CD9;" /></a>
</p>
## Support
### Sponsorship
VT Code is built and maintained in spare time. If it helped you ship or learn
something, a [sponsorship](https://github.com/sponsors/vinhnx) keeps the
project independent.
<p align="center">
<a href="https://github.com/dnhn"><img src="https://avatars.githubusercontent.com/u/2561973" width="80" height="80" alt="@dnhn" style="border-radius: 50%" /></a>
<a href="https://github.com/codemod"><img src="https://avatars.githubusercontent.com/u/78830094" width="80" height="80" alt="@codemod" style="border-radius: 50%" /></a>
<a href="https://github.com/coderabbitai"><img src="https://avatars.githubusercontent.com/u/132028505" width="80" height="80" alt="@coderabbitai" style="border-radius: 50%" /></a>
<a href="https://github.com/KhaiRyth"><img src="https://avatars.githubusercontent.com/u/273723951" width="80" height="80" alt="@KhaiRyth" style="border-radius: 50%" /></a>
</p>
<p align="center">
<a href="https://github.com/sponsors/vinhnx"><img src="https://img.shields.io/badge/%E2%9D%A4%20Sponsor-30363D?style=for-the-badge&logo=github-sponsors&logoColor=#EA4AAA" alt="GitHub Sponsors" height="33" /></a>
<a href="https://buymeacoffee.com/vinhnx"><img src="./resources/screenshots/qr_donate.png" alt="Buy Me a Coffee" width="100" style="border-radius: 12px" /></a>
</p>
## License
First-party code is **MIT OR Apache-2.0**. See [LICENSE](LICENSE).
Third-party code keeps its original licenses: see [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES).