Welcome to the comprehensive documentation for VT Code, a Rust-based terminal coding agent with modular architecture supporting multiple LLM providers and advanced code analysis capabilities.
cargo install vtcode📚 API Documentation | 📦 Crates.io
brew install vtcodeDownload from GitHub Releases for Linux, macOS, or Windows.
VT Code represents a modern approach to AI-powered software development, featuring:
- Single-Agent Reliability (default) - Streamlined, linear agent with robust context engineering
- Decision Ledger - Structured, compact record of key decisions injected each turn for consistency
- Error Recovery & Resilience - Intelligent error handling with pattern detection and context preservation
- Conversation Summarization - Automatic compression when exceeding thresholds with quality assessment
- Multi-Provider LLM Support - Gemini, OpenAI, Anthropic, OpenRouter integration
- Advanced Code Intelligence - Tree-sitter parsers for 6+ programming languages
- Enterprise-Grade Safety - Comprehensive security controls and path validation
- Flexible Configuration - TOML-based configuration with granular policies
- Workspace-First Execution - Full read/write/command capabilities anchored to
WORKSPACE_DIRwith built-in indexing workflows
This documentation is organized to support different user personas and use cases:
VT Code has undergone significant improvements inspired by Anthropic's agent architecture:
- Decision Transparency System - Complete audit trail with reasoning and confidence scores
- Error Recovery & Resilience - Intelligent error handling with pattern detection and multiple recovery strategies
- Conversation Summarization - Automatic compression for extended sessions with quality metrics
- Enhanced Tool Design - Comprehensive specifications with error-proofing and clear usage guidelines
- Configuration Synchronization - Two-way sync between generated configs and existing settings
See CHANGELOG for complete details on these improvements.
New to VT Code? Start with installation and basic usage:
- Getting Started - Installation, configuration, and first steps
- Interactive Mode Reference - Keyboard shortcuts and terminal workflows
- Decision Ledger - How decisions are tracked and injected
- Configuration Guide - Comprehensive configuration options
- Status Line Configuration - Customize the inline prompt footer
Contributing to VT Code? Understand the architecture and development processes:
- Architecture Overview - System design and core components
- Development Guide - Development environment setup
- API Documentation - Technical API references
- Code Standards - Coding guidelines and best practices
- Codex Cloud Setup - Configure Codex Cloud environments for VT Code
- Memory Management - Tune VT Code's AGENTS.md hierarchy for reliable prompts
Deploying VT Code in production? Focus on enterprise features:
- Security Model - Multi-layered security architecture
- Security Audit - Vulnerability analysis and recommendations
- Security Implementation - Security controls and compliance
- Performance Analysis - Optimization and benchmarking
- Provider Guides - LLM provider integration guides
- Decision Ledger - Persistent, compact history of key decisions and constraints
- Error Recovery - Intelligent error handling with pattern detection and context preservation
- Smart Summarization (EXPERIMENTAL) - Automatic conversation compression with importance scoring, semantic similarity detection, and advanced error analysis (disabled by default)
- Conversation Summarization - Automatic compression for long sessions with quality scoring
- Context Compression - Summarizes older turns while preserving ledger, errors, and recent activity
- Tool Traces - Tool inputs/outputs summarized and fed back for continuity
- Tree-Sitter Integration - Syntax-aware parsing for Rust, Python, JavaScript, TypeScript, Go, Java
- Intelligent Search - Ripgrep and Tree-sitter powered code analysis
- Fuzzy File Discovery - Git-aware traversal using
ignorewithnucleo-matcherscoring - Symbol Analysis - Function, class, and variable extraction
- Dependency Mapping - Import relationship analysis
- Code Quality Assessment - Complexity and maintainability scoring
- File Operations - Safe, validated file system operations
- Terminal Integration - Enhanced PTY support with color-coded tool/MCP status banners and interactive commands
- Search & Analysis - Fast text and syntax-aware code search
- Batch Processing - Efficient multi-file operations
- Configuration Management - Dynamic TOML-based settings
VT Code implements a multi-layered security model to protect against prompt injection and argument injection attacks:
- Execution Policy - Command allowlist with per-command argument validation (only 9 safe commands allowed)
- Argument Injection Protection - Explicit blocking of dangerous flags (e.g.,
--pre,-exec,-e) - Workspace Isolation - All operations confined to workspace boundaries with symlink resolution
- Sandbox Integration - Optional Anthropic sandbox runtime for network commands
- Human-in-the-Loop - Three-tier approval system (once/session/permanent)
- Path Validation - Prevents access outside workspace with comprehensive traversal checks
- Command Policies - Allow/deny lists with pattern matching
- Audit Trail - Comprehensive logging of all command executions
- File Size Limits - Configurable resource constraints
- API Key Security - Secure credential management
Security Quick Reference - Security at a glance Security Model - Complete security architecture Security Audit - Vulnerability analysis and testing Security Guide - Best practices and configuration Tool Policies - Command execution policies
- Installation - Get VT Code running in minutes
- Basic Configuration - Set up your environment
- First Chat Session - Try interactive coding assistance
- Architecture Overview - Understand the system design
- Development Setup - Configure development environment
- Decision Ledger - Learn decision tracking and context engineering
- Security Implementation - Enterprise security features
- Provider Integration - LLM provider setup (Gemini, OpenAI, Anthropic, OpenRouter)
- Performance Tuning - Optimization strategies
LLM Routing:
To enable LLM routing: set [router] llm_router_model = "<model-id>".
Budget Tuning:
To tune budgets: add [router.budgets.<class>] with max_tokens and max_parallel_tools.
Trajectory Logs:
Logs for trajectory: check .vtcode/logs/trajectory.jsonl.
WORKSPACE_DIRalways points to the active project root; treat it as the default scope for every command and edit.- Use targeted indexing (directory walks, dependency introspection, metadata extraction) before large changes to stay aligned with the current codebase.
- Keep shell commands and scripts within the workspace unless the workflow explicitly requires external paths.
- Ask for confirmation before operating outside
WORKSPACE_DIRor when interacting with untrusted downloads. - Launch sessions against another repository with
vtcode /abs/path; you can also pass--workspace-dir(alias:--workspace) to other commands when needed.
# Complex task execution with Decision Ledger
./run.sh chat "Implement user authentication system"
# Codebase analysis
./run.sh analyze# Initialize project configuration
./run.sh init
# Generate complete configuration (preserves existing settings)
./run.sh config
# Generate configuration to custom file
./run.sh config --output my-config.toml
# Edit configuration interactively
./run.sh config --edit
# Validate configuration
./run.sh config --validateSmart Configuration Generation: The config command implements two-way synchronization that reads your existing vtcode.toml and generates a complete template while preserving all your customizations.
VT Code is evaluated on industry-standard benchmarks to measure code generation quality and performance:
Latest: gemini-2.5-flash-lite achieves 61.6% pass@1 on the complete HumanEval dataset (164 tasks)
| Metric | Value |
|---|---|
| Pass@1 | 61.6% |
| Median Latency | 0.973s |
| P90 Latency | 1.363s |
| Cost | $0.00 (free tier) |
View Full Benchmark Results 📈 Model Comparison 🔧 Run Your Own Benchmarks
# Run full HumanEval benchmark
make bench-humaneval PROVIDER=gemini MODEL='gemini-2.5-flash-lite'
# Compare multiple models
python3 scripts/compare_benchmarks.py reports/HE_*.json
# Generate visualizations
python3 scripts/generate_benchmark_chart.py reports/HE_*.json --pngVT Code includes comprehensive testing infrastructure:
- Unit Tests - Component-level testing with
cargo nextest run - Integration Tests - End-to-end workflow validation
- Performance Tests - Benchmarking with
cargo bench - Configuration Tests - TOML validation and policy testing
- Code Generation Benchmarks - HumanEval and other standard benchmarks
# Run full test suite
cargo nextest run --workspace
# Run with coverage
cargo tarpaulin
# Performance benchmarking
cargo bench
# Code generation benchmarks
make bench-humaneval
# Linting and formatting
cargo clippy && cargo fmt- Roadmap - Future development plans and milestones
- Changelog - Version history and release notes
- TODO - Current development tasks
- Contributing Guide - How to contribute
- Code Standards - Coding guidelines
- Architecture Decisions - Design rationale
- GitHub Issues - Report bugs and request features
- GitHub Discussions - Community discussions and support
- Documentation - Comprehensive guides and tutorials
- Main README - Project overview and quick reference
- GitHub Repository - Source code and collaboration
- Discussions - Community support
- Security Features - Enterprise-grade security controls
- Single-Agent Coordination - Reliable workflow orchestration with Decision Ledger
- Provider Integration - Multiple LLM provider support
- Performance Optimization - Enterprise-scale performance tuning
This documentation is part of the VT Code project. See the main README for license information.
VT Code builds upon key developments in AI agent technology:
- Anthropic's Agent Patterns - Tool design and safety principles
- Cognition's Context Engineering - Long-running agent reliability and Decision Ledger
- Single-Agent Architecture - Reliable coordination patterns
- Tree-Sitter Ecosystem - Advanced code parsing capabilities
- Rust Community - High-performance systems programming
Documentation Version: 2.2.0 Last Updated: November 2025 VT Code Version: 0.43.6
Ready to get started? Installation Guide
This documentation reflects version 0.43.6 of VT Code, which includes significant enhancements including:
- Decision Ledger system for transparent decision tracking
- Error recovery and resilience with intelligent pattern detection
- Conversation summarization for long-running sessions
- Enhanced Terminal User Interface (TUI) with improved mouse support and text selection
- Two-way configuration synchronization