VT Code is an open-source, Rust-based terminal coding agent that pairs a streamlined TUI with LLM-native code understanding and robust shell safety. It supports multiple LLM providers with automatic failover and efficient context management, and is designed for developers who need precise context handling, secure tool execution, and configurable multi-provider AI workflows.
For installation instructions, see page 1.1 (Getting Started). For detailed architecture documentation, see page 1.2 (System Architecture).
VT Code is a Rust-based terminal coding agent that combines a streamlined TUI with semantic code understanding via Tree-sitter. The system enables developers to interact with AI models through multiple providers while maintaining precise context handling, secure tool execution, and configurable workflows.
Key capabilities:
| Capability | Description |
|---|---|
| LLM-native code understanding | Tree-sitter-based semantic analysis for Rust, Python, JS/TS, Go, Java, Bash |
| Multi-provider support | OpenAI, Anthropic, Gemini, xAI, DeepSeek, Ollama, OpenRouter, Z.AI, Moonshot, LM Studio |
| Shell safety | tree-sitter-bash command validation, execution policy, and sandbox isolation |
| TUI | ratatui-based full and inline terminal UI with streaming output |
| Agent protocols | ACP (Zed), A2A, MCP tool integration |
| Configuration-first | Everything driven by vtcode.toml with environment variable overrides |
Sources: README.md1-14 Cargo.toml1-13 src/lib.rs1-22
The system serves three primary use cases:
| Use Case | Implementation | Entry Point |
|---|---|---|
| Interactive coding sessions | TUI with streaming responses | vtcode CLI command |
| One-off code generation | Direct prompt execution | vtcode ask subcommand |
| IDE integration | ACP bridge for editors | vtcode acp subcommand |
The agent runtime orchestrates LLM interactions, tool execution, and workspace management through a unified configuration system driven by vtcode.toml.
Sources: README.md45-53 src/lib.rs23-40 vtcode-core/src/lib.rs1-27
Package Structure Overview
The workspace is organized as a Cargo workspace with 13 member crates defined in Cargo.toml58-72 The binary package (vtcode) depends on vtcode-core which provides the agent runtime, and both depend on supporting crates for specific functionality:
| Package | Primary Types/Functions | Purpose |
|---|---|---|
vtcode | main, StartupContext, ensure_workspace_trust | CLI entry point, workspace trust |
vtcode-core | Agent, AgentRunner, ToolRegistry, LLMProvider | Agent orchestration and execution |
vtcode-config | VTCodeConfig, AgentConfig | Configuration loading with precedence |
vtcode-bash-runner | BashRunner | Cross-platform shell execution |
vtcode-exec-events | ThreadEvent, ThreadItem | Structured telemetry schema |
vtcode-acp-client | acp_connection, register_acp_connection | Agent Client Protocol implementation |
vtcode-tui | InlineSession, InlineHandle, InlineHeaderContext | TUI widgets and inline session state |
vtcode-llm | Provider abstractions, prototype extraction | Unified LLM client layer (not published) |
vtcode-tools | Tool registry prototype extraction | Modular tool registry (not published) |
vtcode-file-search | File search utilities | Workspace file search |
vtcode-lmstudio | LM Studio provider | Local LM Studio integration |
Sources: Cargo.toml58-72 vtcode-core/Cargo.toml1-25 src/lib.rs164-175 src/acp/mod.rs1-10
Component Responsibilities
| Component | Key Functions/Types | Module Path |
|---|---|---|
VTCodeConfig | load(), from_file() | vtcode-config |
Agent | new(), run() | vtcode-core/src/core/agent/ |
AgentRunner | execute_turn() | vtcode-core/src/core/agent/runner.rs |
ToolRegistry | new(), execute_tool(), initialize_async() | vtcode-core/src/tools/ |
LLMProvider | generate(), stream(), supports_tools() | vtcode-core/src/llm/ |
ToolPolicyManager | new_with_workspace(), get_policy_summary() | vtcode-core/src/tool_policy/ |
Session | new() | vtcode-core/src/session/ |
InlineHandle | Message passing for TUI updates | vtcode-core/src/ui/tui/ |
Sources: vtcode-core/src/lib.rs189-198 vtcode-config/Cargo.toml1-15 src/agent/runloop/ui.rs46-80 vtcode-core/Cargo.toml26-141
Execution Path Details
clap processes arguments into Cli structStartupContext::from_cli() merges configuration sourcesensure_workspace_trust() validates workspace authorization, returns WorkspaceTrustGateResultAgent::new() constructs ToolRegistry and LLM client via make_client()Session::new() establishes InlineHandle for TUI communicationAgentRunner::execute_turn() orchestrates LLM requests and tool executionToolRegistry::execute_tool() validates via ToolPolicyManager before executionBashRunner::execute() runs commands and captures outputThreadEvent structures are serialized for telemetrySources: src/startup.rs src/workspace_trust.rs40-99 src/cli/chat_tools.rs7-33 vtcode-core/src/lib.rs198-209 vtcode-bash-runner/Cargo.toml22-39
Configuration loading follows a strict precedence hierarchy managed by vtcode-config:
Configuration Precedence (highest to lowest):
--model, --provider, --config KEY=VALUE)vtcode.toml in project root~/.vtcode/config.toml managed by DotConfigOPENAI_API_KEY, VT_ACP_ENABLED, etc.)vtcode-configKey Configuration Structs:
| Struct | Key Fields | Module |
|---|---|---|
VTCodeConfig | agent, acp, tools, mcp, security | vtcode-config |
AgentConfig | provider, model, workspace, reasoning_effort | vtcode-config |
AgentClientProtocolConfig | enabled, zed, transport | vtcode-config/src/acp.rs |
DotConfig | preferences, providers, workspace_trust | vtcode-core/src/utils/dot_config.rs10-100 |
WorkspaceTrustStore | entries: HashMap<String, WorkspaceTrustRecord> | vtcode-core/src/utils/dot_config.rs48-58 |
Sources: vtcode-config/Cargo.toml1-15 vtcode-core/src/utils/dot_config.rs10-100 vtcode-core/src/config/acp.rs src/agent/runloop/welcome.rs28-106 README.md125-134
Tool Categories and Implementation
| Tool Name | Function Signature | Implementation Module |
|---|---|---|
unified_exec | execute_bash_command(command, args) | vtcode-bash-runner |
unified_file | read_file(), write_file(), edit_file() | vtcode-core/src/tools/file/ |
unified_search | grep_file(), list_files() | vtcode-core/src/tools/search/ vtcode-file-search |
tree_sitter | analyze_code(), find_symbols() | vtcode-core/src/tools/tree_sitter/ vtcode-indexer |
web_fetch | fetch(url, method) | vtcode-core/src/tools/ |
| MCP tools | Dynamically loaded from rmcp client | vtcode-core/src/mcp/ |
| Agent Skills | Skill-specific functions | vtcode-core/src/skills/ |
Sources: vtcode-core/src/tools/ vtcode-core/src/lib.rs285-288 vtcode-bash-runner/Cargo.toml22-39 vtcode-exec-events/Cargo.toml1-38 README.md149-161
The system supports multiple LLM providers through a unified trait abstraction:
Provider Configuration
| Provider | Config Value | API Key Env Var | Special Features |
|---|---|---|---|
| OpenAI | "openai" | OPENAI_API_KEY | Function calling, streaming |
| Anthropic | "anthropic" | ANTHROPIC_API_KEY | Prompt caching, extended thinking |
| Google Gemini | "gemini" or "google" | GEMINI_API_KEY or GOOGLE_API_KEY | Implicit caching |
| xAI | "xai" | XAI_API_KEY | Grok models |
| DeepSeek | "deepseek" | DEEPSEEK_API_KEY | Reasoning extraction |
| Ollama | "ollama" | (local) | Auto model pull, wire API detection |
| OpenRouter | "openrouter" | OPENROUTER_API_KEY | Model routing |
| Z.AI | "zai" | ZAI_API_KEY | Standard OpenAI format |
| Moonshot | "moonshot" | MOONSHOT_API_KEY | Kimi models |
LLMProvider Trait Methods:
Sources: vtcode-core/src/llm/ vtcode-core/src/lib.rs232 README.md68-72 Cargo.toml1-27
This wiki is organized into the following sections:
| Section | Title | Covers |
|---|---|---|
| 1.1 | Getting Started | Installation, API key setup, first-run |
| 1.2 | System Architecture | Crate structure, component interconnect diagrams |
| 2 | Workspace and Package Structure | All crates, purposes, inter-dependencies |
| 2.1 | Core Library (vtcode-core) | vtcode-core modules: llm, tools, config, ui, mcp, exec |
| 2.2 | CLI Application (vtcode) | main(), Cli, Commands, StartupContext, subcommand dispatch |
| 2.3 | Supporting Libraries | vtcode-config, vtcode-commons, vtcode-llm, vtcode-tools, etc. |
| 2.4 | Execution and Telemetry | vtcode-bash-runner, vtcode-exec-events, ThreadEvent schema |
| 3 | Configuration System | Config loading, merging, precedence |
| 4 | LLM Integration | LLMProvider trait, LLMFactory, provider implementations |
| 5 | Agent System | AgentRunner, run loop, context management, session persistence |
| 6 | Tool System | ToolRegistry, built-in tools, shell/PTY, MCP, security |
| 7 | Terminal User Interface | ratatui TUI, InlineSession, rendering, slash commands |
| 8 | IDE Integration | ACP bridge (ZedAcpAdapter), VS Code extension |
| 9 | Distribution and Release | crates.io, npm, Homebrew, CI/CD |
| 10 | Development | Dev workflow, testing, contributing |
VT Code distributes through multiple package ecosystems:
| Channel | Installation Command | Artifact |
|---|---|---|
| crates.io | cargo install vtcode | Rust package |
| Homebrew | brew install vinhnx/tap/vtcode | macOS/Linux formula |
| npm | npm install -g vtcode | Node.js wrapper |
| GitHub Releases | Direct binary download | Platform-specific archives |
The release process is orchestrated by scripts/release.sh, which:
cargo-releaseSources: README.md17-44 Cargo.toml1-27 docs/guides/zed-acp.md172-189
VT Code provides IDE integration through two protocols:
Agent Client Protocol (ACP)
The ACP bridge enables integration with Zed editor:
vtcode acp subcommand (src/cli/acp.rs8-43)ZedAcpAdapter (src/acp/mod.rs1-9)[acp] section in vtcode.tomlVS Code Extension
The companion extension (vtcode-companion) provides:
Sources: README.md75-110 docs/guides/zed-acp.md1-30 src/cli/acp.rs1-44 src/acp/mod.rs1-9
VT Code implements defense-in-depth security:
Security Layers
Sources: README.md161-173 src/workspace_trust.rs42-241 vtcode-exec-events/Cargo.toml1-15
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.
