Skip to content

README.md

Latest commit

 

History

History
341 lines (235 loc) · 14.6 KB

README.md

File metadata and controls

341 lines (235 loc) · 14.6 KB

VT Code Documentation Hub

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.

Quick Installation

Crates.io Homebrew GitHub release

Choose Your Installation Method

Cargo (Recommended)

cargo install vtcode

API Documentation | Crates.io

Homebrew (macOS)

brew install vtcode

Homebrew Formula

Pre-built Binaries

Download from GitHub Releases for Linux, macOS, or Windows.

What Makes VT Code Special

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
  • LLM-Native Code Understanding - Precise semantic analysis across all modern languages
  • Bash Safety Parsing - Accurate shell command validation via tree-sitter-bash
  • 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_DIR with built-in indexing workflows

Documentation Overview

This documentation is organized to support different user personas and use cases:

Recent Major Enhancements

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.

For Users

New to VT Code? Start with installation and basic usage:

For Developers

Contributing to VT Code? Understand the architecture and development processes:

For Organizations

Deploying VT Code in production? Focus on enterprise features:

Core Capabilities

Context Engineering

  • 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

LLM-Native Code Understanding

  • Semantic Analysis - Deep code understanding across Rust, Python, JavaScript, TypeScript, Go, Java, and more
  • Bash Safety Parsing - Tree-sitter-bash for critical shell command validation
  • Intelligent Search - Ripgrep powered code analysis and discovery
  • Fuzzy File Discovery - Git-aware traversal using ignore with nucleo-matcher scoring
  • Symbol Analysis - LLM-native function, class, and variable extraction
  • Dependency Mapping - Import relationship analysis
  • Code Quality Assessment - Complexity and maintainability scoring via AI analysis

Comprehensive Tool Suite

  • 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
  • GPU Pod Manager - Remote model pod lifecycle management over SSH (feature guide)

Safety & Security

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 Documentation Index - Security docs at a glance Security Model - Complete security architecture Security Web Fetch - Web fetch security model and controls Security Guide - Best practices and configuration Tool Policies - Command execution policies

Quick Start Guide

For New Users

  1. Installation - Get VT Code running in minutes
  2. Basic Configuration - Set up your environment
  3. First Chat Session - Try interactive coding assistance

For Developers

  1. Architecture Overview - Understand the system design
  2. Development Setup - Configure development environment
  3. Decision Ledger - Learn decision tracking and context engineering

For Organizations

  1. Security Implementation - Enterprise security features
  2. Provider Integration - LLM provider setup (Gemini, OpenAI, Anthropic, OpenRouter)
  3. Performance Tuning - Optimization strategies

Usage Patterns

Usage Notes

Trajectory Logs: Logs for trajectory: check .vtcode/logs/trajectory.jsonl.

Workspace-First Operations

  • WORKSPACE_DIR always 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_DIR or 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.

Single-Agent Workflows

# Complex task execution with Decision Ledger
./run.sh chat "Implement user authentication system"

# Codebase analysis
./run.sh analyze

Configuration Management

# 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 --validate

Smart 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.

Benchmarks & Performance

VT Code is evaluated on industry-standard benchmarks to measure code generation quality and performance:

HumanEval Results

Latest: gemini-3-flash-preview 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

Running Benchmarks

# Run full HumanEval benchmark
make bench-humaneval PROVIDER=gemini MODEL='gemini-3-flash-preview'

# Compare multiple models
python3 scripts/compare_benchmarks.py reports/HE_*.json

# Generate visualizations
python3 scripts/generate_benchmark_chart.py reports/HE_*.json --png

Testing & Quality Assurance

VT Code includes comprehensive testing infrastructure:

Test Categories

  • Unit Tests - Component-level testing with cargo test
  • 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

Quality Assurance

# Run full test suite
cargo test --workspace

# Run with coverage
cargo tarpaulin

# Performance benchmarking
cargo bench

# Code generation benchmarks
make bench-humaneval

# Linting and formatting
cargo clippy && cargo fmt

Project Information

Current Status & Roadmap

  • Roadmap - Future development plans and milestones
  • Changelog - Version history and release notes

Development Resources

Support & Community

Getting Help

  • GitHub Issues - Report bugs and request features
  • GitHub Discussions - Community discussions and support
  • Documentation - Comprehensive guides and tutorials

Community Resources

Enterprise 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

License & Attribution

This documentation is part of the VT Code project. See the main README for license information.

Attribution

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 Bash Grammar - Critical shell command validation
  • Rust Community - High-performance systems programming

Documentation Version: 2.1.0 Last Updated: September 2025 VT Code Version: 0.15.9

Ready to get started? Installation Guide

Documentation Version

This documentation reflects version 0.15.9 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