GitHub - vinhnx/VTCode: VT Code is an open-source coding agent with LLM-native code understanding and robust shell safety. Supports multiple LLM providers with automatic failover and efficient context management.
Pangram verdict · v3.3
We believe that this document is a mix of AI-generated, AI-assisted, and human-written content
AI likelihood · overall
MixedArticle text · 1,358 words · 5 segments analyzed
VT Code is an open-source coding agent with LLM-native code understanding and robust shell safety. Supports multiple LLM providers with automatic failover and efficient context management.
Installation Native Installer (Recommended) - No dependencies, instant setup: The default macOS/Linux installer also attempts the recommended ripgrep + ast-grep bundle for enhanced semantic grep and programming language-level understanding (optional). TipOfficial macOS/Linux release archives bundle ghostty-vt/ runtime libraries for richer PTY screen snapshots. VT Code still falls back to the built-in legacy_vt100 backend when those assets are unavailable in non-release or custom installs.
macOS & Linux: curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# Or skip ripgrep + ast-grep during install curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash -s -- --without-search-tools Windows (PowerShell): irm https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.ps1 | iex NoteWindows installs are currently best-effort and may lag behind macOS/Linux release builds. The current release pipeline is still being tuned for cross-based Windows builds, and Windows build minutes can be costly, so Windows artifacts may not be available in every release.
Alternative Installation Methods: # Cargo (Rust package manager) cargo install vtcode
# Homebrew (macOS/Linux) # From homebrew/core (official): brew install vtcode
# From vinhnx/tap (development/bleeding edge): brew tap vinhnx/tap brew install vtcode
# If switching between taps, uninstall first: brew uninstall vtcode brew install vtcode # or: brew install vinhnx/tap/vtcode
# Optional: install the search tools bundle later vtcode dependencies install search-tools Ghostty
VT is not installed through vtcode dependencies install .... Instead, VT Code uses runtime libraries that are either:
Bundled in official macOS/Linux release archives under ghostty-vt/ Copied by the native installers during release installs Staged locally for development with scripts/setup-ghostty-vt-dev.sh Auto-bootstrapped by ./scripts/run.sh and ./scripts/run-debug.sh when the runtime libraries are missing
See Installation Guide, Development Setup, and Ghostty VT Packaging.
Note: If you encounter "installed from different tap" errors, uninstall the existing formula first: brew uninstall vtcode, then install from your preferred tap.
See Installation Guide and Native Installer Guide for more options and troubleshooting. Usage # Set your API key export OPENAI_API_KEY="sk-..."
# Launch VT Code vtcode Skills Support VT Code includes comprehensive support for Skills, following the open Agent Skills standard. Skills enable VT Code to leverage external capabilities and extend its functionality through a standardized skill system.
Skill Discovery: VT Code can discover and load skills from multiple locations with precedence handling Standard Compliance: Fully compliant with the Agent Skills specification for interoperability Multi-Location Support: Skills can be loaded from local directories, remote repositories, or embedded resources Extensible Ecosystem: Integrate with the growing ecosystem of Agent Skills for enhanced capabilities
For more information about skills implementation in VT Code, see Agent Skills Guide. Subagents And Background Helpers VT Code can delegate bounded work to foreground subagents and also run an explicitly configured background subagent as a managed subprocess.
/agent and /agents active inspect delegated agents in place without switching the main session Background subprocesses are opt-in; VT Code no longer ships with a preconfigured default background agent Ctrl+B starts or stops the configured default background subagent only after [subagents.background] is enabled and default_agent is set /subprocesses or Alt+S opens the Local Agents drawer The wide-mode sidebar shows a unified Local Agents section for delegated agents and background subprocesses
The background runtime is configured under [subagents.background]: [subagents.background] enabled = true default_agent = "rust-engineer" refresh_interval_ms = 2000 auto_restore = true toggle_shortcut = "ctrl+b" Supported Providers VT Code works with GitHub Copilot, OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, Z.AI, Moonshot AI, MiniMax, HuggingFace Inference Providers, Ollama (local & cloud), LM Studio (local), and OpenAI-compatible custom providers such as Atlas Cloud. Set the corresponding environment variable for your provider (see Installation Guide for all options). Atlas Cloud Atlas Cloud works through VT Code's [[custom_providers]] support, so you can point VT Code at https://api.atlascloud.ai/v1 without adding a dedicated runtime provider.
[agent] provider = "atlascloud" default_model = "deepseek-ai/deepseek-v4-flash"
[[custom_providers]] name = "atlascloud" display_name = "Atlas Cloud" base_url = "https://api.atlascloud.ai/v1" api_key_env = "ATLASCLOUD_API_KEY" model = "deepseek-ai/deepseek-v4-flash" See Atlas Cloud Integration for the full setup flow and troubleshooting notes. GitHub Copilot Integration VT Code includes first-class support for GitHub Copilot with OAuth device-flow authentication via the official copilot CLI: # Install GitHub Copilot CLI brew install gh-copilot
# Authenticate copilot login
# Or use VT Code's TUI vtcode # Then: /login copilot For detailed setup, see GitHub Copilot Authentication. Agent Protocols VT Code supports multiple agent protocols for integration: Agent Client Protocol (ACP) VT Code can integrate with code editors like Zed. For setup and troubleshooting, refer to the ACP docs. For local development, prefer pointing Zed at a small wrapper script that runs the repo build (target/debug/vtcode or target/release/vtcode) with an explicit --config path, instead of relying on an older installed binary in ~/.local/bin.
Agent2Agent (A2A) Protocol VT Code implements the Agent2Agent (A2A) Protocol, enabling communication and interoperability between AI agents. The A2A protocol supports:
Agent Discovery: Via Agent Cards at /.well-known/agent-card.json Task Lifecycle Management: States like submitted, working, completed, failed Real-time Streaming: Via Server-Sent Events (SSE) Rich Content Types: Text, file, and structured data parts Push Notifications: Webhook-based async updates JSON-RPC 2.0: Over HTTP(S) for interoperability
For more information about A2A protocol support, see A2A Protocol Documentation. Anthropic API Compatibility VT Code provides compatibility with the Anthropic Messages API to help connect existing applications to VT Code, including tools like Claude Code. The server supports:
Messages endpoint at /v1/messages Streaming responses Tool calling Vision (image) support Multi-turn conversations System prompts All major Anthropic API features
For more information about Anthropic API compatibility, see Anthropic API Documentation. Open Responses Specification VT Code conforms to the Open Responses specification, an open, vendor-neutral standard for large language model APIs. This enables interoperable LLM workflows across different providers. Key features of Open Responses conformance:
Unified Item Types: State machine-based items with defined lifecycle states Semantic Streaming: Events describe meaningful transitions, not raw token deltas Agentic Loop Support: Composable tool invocation and message orchestration Extension Points: Provider-specific features via namespaced extensions (e.g., vtcode:file_change)
For more information about Open Responses implementation, see Open Responses Documentation. Agent Trajectory Interchange Format (ATIF) VT Code implements the Agent Trajectory Interchange Format (ATIF) v1.4 for standardized session trajectory export. ATIF captures complete interaction histories — user messages, agent responses, tool calls, observations, and LLM metrics — in a JSON format usable across debugging, visualization, SFT, and RL pipelines.
Complete History: Every agent step, tool invocation, and observation in one file LLM Metrics: Per-step and aggregate token usage, costs, and cache statistics Interoperable: Compatible with Harbor, OpenHands, Gemini CLI, Claude Code, and Codex trajectories Opt-in: Enable via telemetry.atif_enabled = true in vtcode.toml
For more information, see ATIF Trajectory Format Documentation. Authentication VT Code supports secure OAuth 2.0 authentication for seamless account-based access:
OAuth Providers: OpenAI ChatGPT and OpenRouter with PKCE-secured flows Secure Token Storage: OS-native credential stores (Keychain, Credential Manager, Secret Service) Automatic Token Refresh: Transparent token renewal without user intervention Fallback Encryption: AES-256-GCM encrypted files when keyring unavailable
For detailed setup and provider guides, see OAuth Authentication Guide. Configuration VT Code supports a rich set of configuration options, with preferences stored in vtcode.toml. Key configuration features include:
OAuth Settings: Control authentication method and token storage per provider Lifecycle Hooks: Execute shell commands in response to agent events - see Lifecycle Hooks Guide Tool Policies: Control which tools are allowed, prompted, or denied Security Settings: Configure human-in-the-loop approval and workspace boundaries Performance Tuning: Adjust context limits, timeouts, and caching behavior PTY Backend Selection: Ghostty VT is the default backend; it falls back to legacy_vt100 when runtime libraries are unavailable
For full configuration options, see Configuration. For Ghostty VT runtime library packaging details, see Ghostty VT Packaging. CLI Design Principles VT Code follows the Command Line Interface Guidelines and standard UNIX principles to ensure a robust and pipe-friendly experience:
Output Streams: Primary output (e.g., code from ask, events from exec) is sent to stdout. All logs, metadata, reasoning traces, and interaction prompts are sent to stderr. This allows you to safely pipe vtcode output to other tools. # Only the generated code is saved to file; metadata remains on screen vtcode ask "factorial function in rust" > factorial.rs
Standard Arguments: Adheres to GNU/POSIX argument parsing standards using clap, supporting standard flags like --help, --version, and -- separator for positional arguments.