Skip to content

README.md

Latest commit

 

History

History
376 lines (268 loc) · 18.6 KB

README.md

File metadata and controls

376 lines (268 loc) · 18.6 KB
Raw

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 vinhnx/tap/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 - 21+ providers including Gemini, OpenAI, Anthropic, DeepSeek, OpenRouter, Evolink, Qwen, StepFun, Poolside, Ollama, LM Studio, Xiaomi MiMo, Z.AI, Moonshot, MiniMax, HuggingFace
  • 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:

  • Loop Engineering - Worktree isolation for parallel agents, propose/verify sub-agent separation, durable loop state persistence (.vtcode/state/), and token-cost guardrails. See Loop Engineering.

  • Planning Workflow - Iterate on a build plan with /plan and the plan primary agent. The agent can propose planning itself via an "Enter Planning workflow?" confirmation prompt, and you steer it with intent phrases (approve/implement to exit, stay in planning to remain). Approve via a structured review gate and hand off to build/auto. See Planning Workflow.

  • Primary Agent Switching & Mode Guard - Switch main-session agents (plan/build/auto) with Tab; mode switches lock during a turn to keep tool-access and instructions consistent.

  • Automatic Compaction & Memory Envelope - Unified compaction orchestration with a shared memory envelope as the single source of truth for both runloops.

  • /checkup Command - Configuration diagnostics that surface reversible, confirm-before-apply optimizations (e.g. tool-result clearing, client tool search, token-efficiency warnings).

  • GPT-5.6 Models - Added support for OpenAI's GPT-5.6 family across configurations.

  • GLM-5.2 Model Support - Zhipu AI's latest model with cache metrics in stream handling

  • Byte-Range File Reading - Large file reading with offset and page size parameters for efficient partial reads

  • Kimi K2.7 Code Model - Moonshot's latest code-focused model across all configurations

  • GPT-5-Codex Integration - OpenAI's Codex model with Responses API support

  • Cross-Platform Process Groups - Proper process group management on Windows via platform-specific APIs

  • Signal Handling Architecture - Comprehensive Ctrl+C / SIGINT priority guarantees with double-Ctrl+C emergency exit

  • Compile-Time Tool Validation - Pre-main validation of tool name constants for early error detection

  • Provider Stream Refactoring - Simplified stream handling across DeepSeek, StepFun, and ZAI providers

  • Decision Transparency System - Complete audit trail with reasoning and confidence scores

  • Error Recovery & Resilience - Intelligent error handling with pattern detection and multiple recovery strategies

  • Advanced Code Search - Bounded definitions, syntactic usages, literal text, and matching paths through code_search in the advanced VT Code profile

  • Web Search & Fetch — web_search and defuddle_fetch tools with TOML-driven network allowlist and domain-scoped approval caching

  • Post-Tool Recovery Cycles — Automatic detection and cap enforcement for post-tool recovery loops with temporary file cleanup

  • CLI did you mean? — Fuzzy suggestions for unrecognized commands with colorized output

  • Session Resume — /continue slash command to resume the most recent session

  • Loop Detection Hardening — Blocked-streak fuse prevents false positives; read-extent-aware duplicate detection

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 shell search through exec_command.cmd and focused literal code_search in the advanced profile
  • 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 shell search through rg, plus advanced bounded code search through 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: 3.1.0 Last Updated: June 28, 2026 VT Code Version: 0.133.21

Ready to get started? Installation Guide

Documentation Version

This documentation reflects version 0.133.21 of VT Code, which includes significant enhancements including:

  • GLM-5.2, Kimi K2.7, and GPT-5-Codex model support
  • Byte-range file reading for large files
  • Cross-platform process group management
  • Signal handling architecture with emergency exit
  • 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
  • web_search and defuddle_fetch tools with TOML-driven network allowlist
  • query-led code_search for definitions, syntactic usages, literal text, and matching paths in the advanced VT Code profile
  • Post-tool recovery cycle tracking with cap checks and temporary file cleanup
  • CLI did you mean? suggestions for unrecognized commands
  • /continue command to resume the most recent session
  • Loop detection improvements with blocked-streak fuse and read-extent awareness
  • Colorized CLI suggestions and case-insensitive StatusLineMode deserialization