Highlights

• Multi-provider agent with first-class integrations for OpenAI, Anthropic, xAI, DeepSeek, Gemini, and OpenRouter, including auto-failover and cost guards.
• Semantic code intelligence using tree-sitter parsers for Rust, Python, JavaScript, TypeScript, Go, and Java, combined with ast-grep powered structural search and refactors.
• Modern terminal experience built with Ratatui: mouse support, streaming PTY output, slash commands, customizable Ciapre-inspired theming, and ANSI-accurate rendering.
• Workspace aware by default: Git-aware fuzzy navigation, boundary enforcement, command allowlists, and human-in-the-loop confirmations.
• Config driven: every agent behavior is controlled via vtcode.toml, backed by constants in vtcode-core/src/config/constants.rs and up-to-date model IDs in docs/models.json.

Quickstart

Installing and running VT Code

VT Code can be installed using multiple package managers depending on your preference:

Using Cargo (Rust package manager) - Recommended for Rust developers:

cargo install vtcode

Using Homebrew (macOS only):

brew install vinhnx/tap/vtcode

Using npm (Node.js package manager) - Cross-platform:

npm install -g vtcode

After installation with any method, simply run vtcode to get started:

vtcode

Configuration

Set your API key for your preferred provider:

export OPENAI_API_KEY="your_key_here"
# or
export ANTHROPIC_API_KEY="your_key_here"
# or
export XAI_API_KEY="your_key_here"
# or
export GEMINI_API_KEY="your_key_here"
# or
export OPENROUTER_API_KEY="your_key_here"

Alternatively, create a .env file in your project directory:

# .env file
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
XAI_API_KEY=your_anthropic_key_here
GEMINI_API_KEY=your_gemini_key_here
OPENROUTER_API_KEY=your_openrouter_key_here

VT Code supports advanced configuration via vtcode.toml. See Configuration for details.

Getting Started

Launch the agent with explicit provider/model flags or rely on the defaults from vtcode.toml:

vtcode --provider openai --model gpt-5-codex

Persist your preferred defaults in configuration rather than hardcoding them:

[agent]
provider = "openai"
default_model = "gpt-5-codex"

Model identifiers should always reference vtcode-core/src/config/constants.rs and docs/models.json to stay aligned with vetted releases.

Usage

• Launch interactive mode with your preferred provider/model:

  vtcode --provider openai --model gpt-5-codex
  

• Run a single prompt with streaming output (scripting friendly):

  vtcode ask "Summarize diagnostics in src/lib.rs"
  

• Execute a command with tool access disabled (dry run):

  vtcode --no-tools ask "Review recent changes in src/main.rs"
  

• When developing locally, the debug script mirrors production defaults:

  ./run-debug.sh
  

CLI options are discoverable via vtcode --help or /help inside the REPL. All defaults live in vtcode.toml, including provider fallbacks, tool allowlists, streaming options, and safety policies.

Architecture Overview

VT Code is composed of a reusable core library plus a thin CLI binary:

• vtcode-core/ contains the agent runtime: provider abstractions (llm/), tool registry (tools/), configuration loaders, and tree-sitter integrations.
• src/main.rs wires the CLI, TUI, and runtime together using clap for argument parsing and Ratatui for rendering.
• MCP (Model Context Protocol) tools extend the agent with contextual resources; configuration lives in vtcode.toml and enables systems like Serena MCP for journaling and memory.
• Tree-sitter parsers and ast-grep power semantic analysis; both are orchestrated asynchronously with Tokio for responsive command handling.

Design goals prioritize composability, guarded execution, and predictable performance. The architecture document in docs/ARCHITECTURE.md dives deeper into module responsibilities and extension hooks.

Core Features

Multi-Platform Installation

• Cargo: cargo install vtcode - Install directly from crates.io
• Homebrew: brew install vinhnx/tap/vtcode - macOS package manager installation
• npm: npm install -g vtcode - Node.js package manager installation
• GitHub Releases: Pre-built binaries for macOS, Linux, and Windows

Multi-Provider AI Support

• OpenAI, Anthropic, xAI, OpenRouter, DeepSeek, and Gemini integration
• Automatic provider selection and failover
• Cost optimization with safety controls
• Support for the latest models including GPT-5, GPT-5 Codex, Grok 4, Grok Code Fast, Claude 4.1 Opus, Claude 4 Sonnet, and Qwen3 Coder Plus

Enhanced Terminal User Interface

• Modern TUI with mouse support and text selection
• Real-time terminal command output with ANSI color support and PTY streaming
• Customizable themes with my own Ciapre theme palette (or Catppuccin via config)
• Interactive slash commands with auto-suggestions
• Smooth scrolling and navigation controls
• Dedicated status bar with contextual information

Advanced Code Intelligence

• Tree-sitter parsing for 6+ languages (Rust, Python, JavaScript, TypeScript, Go, Java)
• Semantic code analysis and pattern recognition
• Intelligent refactoring and optimization suggestions
• Git-aware fuzzy file search backed by the ignore and nucleo-matcher crates
• Code navigation and symbol lookup

Enterprise Security

• Workspace boundary enforcement
• Configurable command allowlists
• Human-in-the-loop controls for safety
• Comprehensive audit logging
• Secure API key management

Modular Architecture

• Trait-based tool system for extensibility
• Multi-mode execution (terminal, PTY, streaming)
• Intelligent caching and performance optimization
• Plugin architecture for custom tools
• Configurable agent workflows

Configuration Reference

• All agent knobs live in vtcode.toml; never hardcode credentials or model IDs.
• Constants (model aliases, file size limits, defaults) are centralized in vtcode-core/src/config/constants.rs.
• The latest provider-specific model identifiers are tracked in docs/models.json; update it alongside configuration changes.
• Safety settings include workspace boundary enforcement, command allow/deny lists, rate limits, and telemetry toggles.

Refer to the guides under docs/project/ for deep dives on providers, tools, and runtime profiles.

Development Workflow

• cargo check for fast validation; cargo clippy --workspace --all-targets to enforce linting.
• Format with cargo fmt and run cargo test for unit and integration coverage.
• ./run-debug.sh launches the debug build with live reload-friendly options.
• Benchmarks live in benches/, and additional examples belong in tests/ (avoid ad-hoc scripts).
• Ensure configuration updates are reflected in docs/project/ and docs/models.json when relevant.

Documentation

• Getting Started - Installation and basic usage
• Configuration - Advanced configuration options
• Architecture - Technical architecture details
• Advanced Features - Safety controls and debug mode
• API Reference - Complete API documentation
• Contributing - Development guidelines

License

This project is licensed under the MIT License - see LICENSE for details.