This document provides a high-level introduction to VTCode's architecture, workspace organization, and core systems. It serves as the entry point for understanding how VTCode operates as a terminal coding agent with semantic intelligence, multi-provider LLM support, and defense-in-depth security.
For detailed workspace structure, see Workspace Structure. For in-depth architecture discussion, see Core Architecture. For installation and configuration instructions, see Getting Started.
VTCode is a Rust-based terminal coding agent built for long-running autonomous workflows. It features OS-native sandboxing, support for over 21 LLM providers, and an extensible architecture via "Skills" and open protocols README.md18-30 It supports providers ranging from cloud giants like Anthropic and OpenAI to local inference via Ollama and LM Studio README.md66-77
The system is structured as a Cargo workspace containing multiple specialized crates Cargo.toml107-127 The architecture prioritizes functional separation, with a core agent loop, a dedicated TUI framework, and modular tool specifications vtcode-core/Cargo.toml112-131
Security is a foundational pillar comprising tool policy enforcement, workspace trust zones, process hardening, and human-in-the-loop approval mechanisms to ensure safe tool invocation and code execution README.md28
Sources: README.md18-30 README.md66-77 Cargo.toml107-127 vtcode-core/Cargo.toml112-131
This diagram maps high-level natural language system components onto concrete Rust code entities, showing VTCode’s main core components and their relationships:
The vtcode binary manages initialization, then delegates to the runtime orchestration in vtcode-core Cargo.toml128 The runtime orchestrates the agent loop, utilizing vtcode-llm for model interaction and vtcode-exec-events as the authoritative event contract vtcode-llm/Cargo.toml46-47 Tools are managed via a registry that integrates Model Context Protocol (MCP) servers, native "Skills", and shell execution through a sandboxed vtcode-bash-runner vtcode-core/Cargo.toml126-131
Sources: Cargo.toml128 vtcode-llm/Cargo.toml46-47 vtcode-core/Cargo.toml126-131 vtcode-core/src/agent/runloop/unified/state.rs1-10
VTCode is organized as a modular Cargo workspace to maintain clear functional separation Cargo.toml107-127
Notable workspace components:
vtcode-core: The heart of the system, managing the agent loop, prompts, and tool orchestration vtcode-core/Cargo.toml2-7vtcode-llm: Unified provider abstraction for 21+ LLMs, supporting streaming and model capability detection vtcode-llm/Cargo.toml7-14vtcode-ui: A terminal UI built with ratatui, featuring a design system and ANSI rendering vtcode-core/Cargo.toml105-109vtcode-bash-runner: Cross-platform shell execution with sandbox support vtcode-bash-runner/Cargo.toml6-13vtcode-mcp: Implementation of the Model Context Protocol for tool discovery vtcode-core/Cargo.toml129vtcode-safety: Logic for command safety detection and execution policies vtcode-core/Cargo.toml127For more information, see Workspace Structure.
Sources: Cargo.toml107-127 vtcode-core/Cargo.toml2-131 vtcode-llm/Cargo.toml7-14 vtcode-bash-runner/Cargo.toml6-13
VTCode operates via a turn-based execution model managed by AgentRunner vtcode-core/src/agent/runloop/unified/turn/session_loop_runner/mod.rs1-20 Each turn processes LLM requests, executes tools, and manages state transitions CHANGELOG.md77-83 The system supports full automation via a plan-build-evaluate harness README.md57
For details, see Core Architecture.
The vtcode-llm crate abstracts model-specific details. It supports streaming, prompt caching, and specific features like "reasoning" effort levels vtcode-llm/Cargo.toml7-14 It integrates with rig-core and openai-harmony for robust client implementations vtcode-llm/Cargo.toml27-31
Tools are the primary way agents interact with the world. VTCode supports:
unified_file, unified_search) CHANGELOG.md112-113Security is enforced at multiple levels:
vtcode-safety vtcode-core/Cargo.toml127VTCode acts as a bridge between LLMs and various environments:
Sources: README.md54-65 vtcode-core/Cargo.toml2-131 vtcode-llm/Cargo.toml7-31 CHANGELOG.md77-113
