vtcode-commons 0.54.3

Shared traits for paths, telemetry, and error reporting reused across VT Code component extractions
Documentation

Documents

  • Ask Google Gemini CodeWiki
  • Ask Devin DeepWiki

Installation

macOS & Linux:

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.ps1 | iex

Alternative Installation Methods:

# Cargo (Rust package manager - Recommended)
cargo install vtcode

# Homebrew (macOS/Linux)
brew install vinhnx/tap/vtcode

See Installation Guide for more options and troubleshooting.

Usage

# Set your API key
export OPENAI_API_KEY="sk-..."

# Launch VT Code
vtcode

Supported Providers

VT Code works with OpenAI, Anthropic, Google Gemini, xAI, DeepSeek, OpenRouter, Z.AI, Moonshot AI, MiniMax, HuggingFace Inference Providers, Ollama (local & cloud), and LM Studio (local).

Set the corresponding environment variable for your provider (see Installation Guide for all options).

Agent Protocols

VT Code supports multiple agent protocols for integration:

Agent Client Protocol (ACP)

VT Code can integrate with code editors like Zed. To configure ACP, refer to the ACP docs.

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.

CLI Commands for A2A

# Serve VTCode as an A2A agent (requires a2a-server feature)
vtcode a2a serve --port 8080

# Discover a remote agent
vtcode a2a discover https://agent.example.com

# Send a task to an agent
vtcode a2a send-task https://agent.example.com "Help me refactor this code"
vtcode a2a send-task https://agent.example.com "Help me refactor" --stream

# List tasks
vtcode a2a list-tasks https://agent.example.com
vtcode a2a list-tasks https://agent.example.com --context-id my-conversation

# Get task details
vtcode a2a get-task https://agent.example.com task-123

# Cancel a task
vtcode a2a cancel-task https://agent.example.com task-123

Configuration

VT Code supports a rich set of configuration options, with preferences stored in vtcode.toml. Key configuration features include:

  • 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

For full configuration options, see Configuration.

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.

Key Features

  • Security First: Multi-layered security model with execution policy, tool policies, and argument injection protection
  • Multi-Provider AI: OpenAI, Anthropic, xAI, DeepSeek, Gemini, Z.AI, Moonshot AI, OpenRouter, MiniMax, Ollama (local)
  • Code Intelligence: Tree-sitter powered code navigation with go-to-definition, find-references, hover, and symbol search (Rust, Python, JavaScript/TypeScript, Go, Java, Swift, Bash)
  • Smart Tools: Built-in code analysis, file operations, terminal commands, and refactoring
  • Agent Skills: Comprehensive skills location system with multi-location support and precedence handling, aligned with the open Agent Skills standard (docs)
  • Editor Integration: Native support for Zed IDE via Agent Client Protocol (ACP)
  • Lifecycle Hooks: Execute custom shell commands in response to agent events for context enrichment, policy enforcement, and automation (docs)
  • Context Management: Advanced token budget tracking and context curation
  • TUI Interface: Rich terminal user interface with real-time streaming

Security & Safety

VT Code implements a defense-in-depth security model to protect against prompt injection and argument injection attacks:

  • Execution Policy: Command allowlist with per-command argument validation
  • Workspace Isolation: All operations confined to workspace boundaries
  • Tool Policies: Configurable allow/deny/prompt policies for MCP tools
  • Human-in-the-Loop: Configurable approval system for sensitive operations
  • Audit Trail: Comprehensive logging of all command executions

See Security Model for details.

Docs & Examples

Visual Studio Code Extension

VT Code is available as an VS Code extension.

The original VT Code extension for Visual Studio Code with full semantic code understanding and AI assistance.

VT Code is also compatible with other VS Code-compatible editors:

Compatible with Cursor, Windsurf, and other VS Code-compatible editors through the Open VSX registry.

For installation instructions and download links for other IDEs, visit our IDE Downloads page. For troubleshooting, see the IDE Integration Troubleshooting Guide.

Support VT Code Development

I build VT Code in my free time as a passion project to research and explore how coding agents work in practice. If you find VT Code useful, please consider supporting my work with a coffee via BuyMeACoffee:

BuyMeACoffee

QR Code

Your support means the world to me, thank you!

License

This repository is licensed under the MIT License.