Overview

Relevant source files

• .vtcode/tool-policy.json
• AGENTS.md
• Cargo.lock
• Cargo.toml
• README.md
• docs/guides/zed-acp.md
• docs/models.json
• docs/project/TODO.md
• src/acp/mod.rs
• src/cli/acp.rs
• src/lib.rs
• vtcode-acp-client/Cargo.toml
• vtcode-bash-runner/Cargo.toml
• vtcode-commons/Cargo.toml
• vtcode-config/Cargo.toml
• vtcode-core/Cargo.toml
• vtcode-core/src/config/acp.rs
• vtcode-core/src/config/models.rs
• vtcode-core/src/core/interfaces/acp.rs
• vtcode-core/src/prompts/system.rs
• vtcode-core/src/tools/command.rs
• vtcode-core/src/tools/mod.rs
• vtcode-core/src/tools/pty.rs
• vtcode-core/src/tools/registry/builtins.rs
• vtcode-core/src/tools/registry/declarations.rs
• vtcode-core/src/tools/registry/executors.rs
• vtcode-core/src/tools/registry/mod.rs
• vtcode-core/src/tools/types.rs
• vtcode-exec-events/Cargo.toml
• vtcode-indexer/Cargo.toml
• vtcode-llm/Cargo.toml
• vtcode-markdown-store/Cargo.toml
• vtcode-tools/Cargo.toml
• vtcode.toml
• vtcode.toml.example

VTCode is a Rust-based terminal coding agent that combines LLM-native code understanding with multi-provider AI orchestration, secure tool execution, and a modular architecture. This page provides a high-level introduction to the system's purpose, workspace structure, execution model, and core subsystems.

For detailed information on specific subsystems:

• Cargo workspace layout and crate dependencies: see Cargo Workspace Structure
• Component architecture and interaction patterns: see System Architecture
• Installation and setup procedures: see Getting Started
• Agent execution runtime and turn loop: see Agent Execution
• Tool system design and security: see Tool System
• LLM provider integration: see LLM Integration

---

Purpose and Scope

VTCode is a terminal-based AI coding assistant designed for developers who require:

1. Precise context management: Token budget tracking, incremental system prompts, and history normalization to stay within LLM context windows
2. Multi-provider flexibility: Support for 10+ LLM providers with automatic failover and model-specific optimizations
3. Secure tool execution: Multi-layered safety system including command validation, sandbox enforcement, and human-in-the-loop approval
4. Protocol interoperability: Native support for Agent Client Protocol (ACP), Model Context Protocol (MCP), and Agent-to-Agent (A2A) communication

The system follows a turn-based execution model where each turn consists of LLM interaction, tool execution, and state persistence, enabling resumable sessions and checkpointing.

Sources: README.md1-280 src/lib.rs1-22 AGENTS.md1-162

---

System Architecture at a Glance

VTCode is structured as a 13-member Cargo workspace with clear separation of concerns. The core library (vtcode-core) provides reusable agent runtime logic, while the binary crate (vtcode) implements CLI and TUI interfaces.

Diagram: Cargo workspace dependency graph showing modular architecture

Sources: Cargo.toml94-112 AGENTS.md18-37

---

Execution Flow Overview

VTCode operates through a turn-based agent loop orchestrated by the AgentRunner. Each turn processes user input, invokes LLM APIs, executes tools, and persists state.

Diagram: Turn-based execution flow from user input to state persistence

The key classes in this flow:

Class	Location	Purpose
StartupContext	src/cli/startup.rs	CLI argument parsing and workspace resolution
AgentRunner	vtcode-core/src/agent/runner.rs	Turn orchestration and LLM interaction
ThreadRuntimeHandle	vtcode-core/src/session/	Session state management
ContextManager	vtcode-core/src/context/	System prompt construction and token budgets
ToolRegistry	vtcode-core/src/tools/registry/mod.rs112-164	Tool discovery and execution
SessionArchive	vtcode-markdown-store/	Markdown-backed session persistence

Sources: vtcode-core/src/agent/runner.rs src/cli/startup.rs vtcode-core/src/tools/registry/mod.rs112-164

---

Core Subsystems

Agent Runtime (vtcode-core)

The vtcode-core crate provides the central orchestration layer, implementing:

• AgentRunner: Turn-based execution loop with streaming support
• ContextManager: Token budget tracking and history normalization (vtcode-core/src/context/)
• SessionManager: Archive/resume/fork capabilities (vtcode-core/src/session/)
• ToolRegistry: Unified tool facade with circuit breakers (vtcode-core/src/tools/registry/mod.rs112-164)

Key configuration sources:

1. CLI arguments (--model, --provider)
2. Environment variables (ANTHROPIC_API_KEY, VTCODE_PROVIDER)
3. Project vtcode.toml (vtcode.toml1-1346)
4. Global ~/.vtcode/vtcode.toml
5. Built-in defaults (vtcode-config/)

Sources: vtcode-core/Cargo.toml1-220 Cargo.toml94-112 vtcode.toml1-1346

---

Tool System (vtcode-tools, vtcode-core/src/tools/)

VTCode implements a unified tool facade pattern to reduce LLM cognitive load. Instead of exposing 30+ individual tools, it provides three high-level tools that multiplex internally based on an action parameter:

Tool	Actions	Purpose
unified_exec	run, write, poll, continue, inspect, list, close	Shell execution and PTY management
unified_file	read, write, edit, patch, delete, move, copy	File operations with diff-based editing
unified_search	grep, list, intelligence, tools, errors, agent, web, skill	Search and discovery operations

Safety Pipeline:

1. Preflight Validation: Schema checks, argument normalization (vtcode-core/src/tools/registry/executors.rs1-300)
2. Policy Gateway: Consult .vtcode/tool-policy.json (.vtcode/tool-policy.json1-319)
3. Permission Flow: Human approval for sensitive operations
4. Sandbox Manager: Linux landlock/seccomp or macOS seatbelt enforcement (vtcode-core/src/sandboxing/)

Diagram: Unified tool facade execution pipeline

Sources: vtcode-core/src/tools/registry/declarations.rs30-66 vtcode-core/src/tools/registry/executors.rs1-300 .vtcode/tool-policy.json1-319

---

LLM Integration (vtcode-llm, vtcode-core/src/llm/)

VTCode abstracts 10+ LLM providers behind the LLMProvider trait, enabling seamless switching and failover:

Provider	Environment Variable	Capabilities
OpenAI	OPENAI_API_KEY	GPT-5, GPT-5.1, GPT-5.2, o3, o4-mini with reasoning
Anthropic	ANTHROPIC_API_KEY	Claude Sonnet 4.6, Haiku 4.5 with prompt caching
Google	GOOGLE_API_KEY	Gemini 3.1 Pro, 3.0 Flash with URL context
DeepSeek	DEEPSEEK_API_KEY	DeepSeek-V3 with prompt caching
OpenRouter	OPENROUTER_API_KEY	Unified gateway to 100+ models
Ollama	OLLAMA_BASE_URL	Local models via REST API
LM Studio	LMSTUDIO_BASE_URL	Local models via OpenAI-compatible API
Z.AI	ZAI_API_KEY	Proprietary models
Moonshot	MOONSHOT_API_KEY	Chinese market models
MiniMax	MINIMAX_API_KEY	Multi-modal models

Model catalog and capabilities are defined in docs/models.json1-1000 which serves as the single source of truth for model identifiers, context windows, and feature flags.

Sources: docs/models.json1-1000 vtcode-llm/Cargo.toml1-50 vtcode-core/src/llm/

---

Configuration System (vtcode-config)

VTCode uses a multi-layer precedence system:

CLI args > Env vars > Project vtcode.toml > Global ~/.vtcode/vtcode.toml > Defaults

Key configuration files:

File	Purpose
vtcode.toml	Primary configuration with TOML schema (vtcode.toml1-1346)
.vtcode/tool-policy.json	Per-tool execution policies (allow/deny/prompt) (.vtcode/tool-policy.json1-319)
docs/models.json	Model catalog with capabilities and pricing (docs/models.json1-1000)
AGENTS.md	Agent behavior guidelines loaded into system prompt (AGENTS.md1-162)

The ConfigBuilder merges layers and validates constraints before creating the final AgentConfig instance.

Sources: vtcode-config/Cargo.toml1-71 vtcode.toml1-1346 .vtcode/tool-policy.json1-319

---

Integration Protocols

VTCode exposes three protocol layers for external integration:

Agent Client Protocol (ACP)

Enables IDE integration (notably Zed) via stdio transport:

Diagram: ACP protocol bridge for Zed integration

Configuration: vtcode.toml5-10 vtcode.toml11-45

Sources: src/acp/zed.rs docs/guides/zed-acp.md1-200

---

Model Context Protocol (MCP)

Enables external tool providers to register capabilities dynamically:

• Provider Management: vtcode mcp add <provider>, vtcode mcp login <provider>
• Transport: stdio, HTTP, or child-process
• Tool Discovery: Automatic registration in ToolRegistry with allowlist filtering

Configuration: .vtcode/tool-policy.json180-318

Sources: vtcode-core/src/mcp/ .vtcode/tool-policy.json180-318

---

Agent-to-Agent (A2A) Protocol

Implements JSON-RPC 2.0 over HTTP(S) with:

• Agent Card: /.well-known/agent-card.json for capability discovery
• Task Lifecycle: States (submitted, working, completed, failed)
• Streaming: Server-Sent Events (SSE) for real-time updates
• Webhooks: Push notifications for async task completion

Sources: README.md84-93 docs/a2a/a2a-protocol.md

---

Distribution Channels

VTCode is distributed through multiple channels:

Channel	Purpose	Update Command
npm	Cross-platform installer with postinstall.js binary download	npm install -g vtcode
Homebrew	macOS/Linux package manager with formula auto-updates	brew install vinhnx/tap/vtcode
crates.io	Rust package registry for source builds	cargo install vtcode
GitHub Releases	Binary artifacts for all platforms with checksums	Download from releases page
Native Installers	Shell/PowerShell scripts for direct binary installation	curl -fsSL ... | bash

The release process is orchestrated by scripts/release.sh, which:

1. Bumps versions in Cargo.toml and package.json
2. Builds macOS binaries locally (x86_64 + aarch64 → Universal)
3. Triggers GitHub Actions for Linux (gnu + musl) and Windows (MSVC)
4. Downloads CI artifacts and assembles release package
5. Updates Homebrew formula with new SHA256 checksums
6. Publishes to npm with platform-specific binaries

Sources: README.md17-43 scripts/release.sh

---

Next Steps

For deeper exploration of specific subsystems:

• Workspace layout and build profiles: See Cargo Workspace Structure
• Component interaction and data flow: See System Architecture
• Installation and first-run setup: See Getting Started
• Turn loop and execution semantics: See Agent Execution
• Tool implementation and security: See Tool System
• LLM provider implementation: See LLM Integration
• TUI components and rendering: See User Interface
• Configuration reference: See Configuration
• Protocol specifications: See Editor and Protocol Integrations

Sources: README.md1-280 AGENTS.md1-162 Cargo.toml1-309