Crate vtcode_core 

vtcode-core - Runtime for VT Code

vtcode-core powers the VT Code terminal coding agent. It provides the reusable building blocks for multi-provider LLM orchestration, tool execution, semantic code analysis, and configurable safety policies.

Highlights

• Provider Abstraction: unified LLM interface with adapters for OpenAI, Anthropic, xAI, DeepSeek, Gemini, and OpenRouter, including automatic failover and spend controls.
• Prompt Caching: cross-provider prompt caching system that leverages provider-specific caching capabilities (OpenAI’s automatic caching, Anthropic’s cache_control blocks, Gemini’s implicit/explicit caching) to reduce costs and latency, with configurable settings per provider.
• Semantic Workspace Model: incremental tree-sitter parsing for Rust, Python, JavaScript, TypeScript, Go, and Java augmented by ast-grep based structural search and refactoring.
• Tool System: trait-driven registry for shell execution, file IO, search, and custom commands, with Tokio-powered concurrency and PTY streaming.
• Configuration-First: everything is driven by vtcode.toml, with model, safety, and automation constants centralized in config::constants and curated metadata in docs/models.json.
• Safety & Observability: workspace boundary enforcement, command allow/deny lists, human-in-the-loop confirmation, and structured event logging.

Architecture Overview

The crate is organized into several key modules:

• config/: configuration loader, defaults, and schema validation.
• llm/: provider clients, request shaping, and response handling.
• tools/: built-in tool implementations plus registration utilities.
• context/: conversation management, summarization, and memory.
• executor/: async orchestration for tool invocations and streaming output.
• tree_sitter/: language-specific parsers, syntax tree caching, and semantic extraction helpers.
• core/prompt_caching: cross-provider prompt caching system that leverages provider-specific caching mechanisms for cost optimization and reduced latency.

Quickstart

use vtcode_core::{Agent, VTCodeConfig};

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // Load configuration from vtcode.toml or environment overrides
    let config = VTCodeConfig::load()?;

    // Construct the agent runtime
    let agent = Agent::new(config).await?;

    // Execute an interactive session
    agent.run().await?;

    Ok(())
}

Extending VT Code

Register custom tools or providers by composing the existing traits:

use vtcode_core::tools::{ToolRegistry, ToolRegistration};

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let workspace = std::env::current_dir()?;
    let mut registry = ToolRegistry::new(workspace);

    let custom_tool = ToolRegistration {
        name: "my_custom_tool".into(),
        description: "A custom tool for specific tasks".into(),
        parameters: serde_json::json!({
            "type": "object",
            "properties": { "input": { "type": "string" } }
        }),
        handler: |_args| async move {
            // Implement your tool behavior here
            Ok(serde_json::json!({ "result": "success" }))
        },
    };

    registry.register_tool(custom_tool).await?;
    Ok(())
}

For a complete tour of modules and extension points, read docs/ARCHITECTURE.md and the guides in docs/project/.

Agent Client Protocol (ACP)

VT Code’s binary exposes an ACP bridge for Zed. Enable it via the [acp] section in vtcode.toml, launch the vtcode acp subcommand, and register the binary under agent_servers in Zed’s settings.json. Detailed instructions and troubleshooting live in the Zed ACP integration guide, with a rendered summary on docs.rs.

Bridge guarantees

• Tool exposure follows capability negotiation: read_file stays disabled unless Zed advertises fs.read_text_file.
• Each filesystem request invokes session/request_permission, ensuring explicit approval within the editor before data flows.
• Cancellation signals propagate into VT Code, cancelling active tool calls and ending the turn with StopReason::Cancelled.
• ACP plan entries track analysis, context gathering, and response drafting for timeline parity with Zed.
• Absolute-path checks guard every read_file argument before forwarding it to the client.
• Non-tool-capable models trigger reasoning notices and an automatic downgrade to plain completions without losing plan consistency. VTCode Core Library

This crate provides the core functionality for the VTCode agent, including tool implementations, LLM integration, and utility functions.

Re-exports

pub use bash_runner::BashRunner;

pub use cli::args::Cli;

pub use cli::args::Commands;

pub use code::code_completion::CompletionEngine;

pub use code::code_completion::CompletionSuggestion;

pub use commands::stats::handle_stats_command;

pub use config::types::AnalysisDepth;

pub use config::types::CapabilityLevel;

pub use config::types::CommandResult;

pub use config::types::CompressionLevel;

pub use config::types::ContextConfig;

pub use config::types::LoggingConfig;

pub use config::types::OutputFormat;

pub use config::types::PerformanceMetrics;

pub use config::types::ReasoningEffortLevel;

pub use config::types::SessionInfo;

pub use config::types::ToolConfig;

pub use config::AgentClientProtocolConfig;

pub use config::AgentClientProtocolTransport;

pub use config::AgentClientProtocolZedConfig;

pub use config::AgentClientProtocolZedToolsConfig;

pub use config::AgentConfig;

pub use config::VTCodeConfig;

pub use core::agent::core::Agent;

pub use core::context_compression::CompressedContext;

pub use core::context_compression::ContextCompressionConfig;

pub use core::context_compression::ContextCompressor;

pub use core::conversation_summarizer::ConversationSummarizer;

pub use core::performance_profiler::PerformanceProfiler;

pub use core::prompt_caching::CacheStats;

pub use core::prompt_caching::PromptCache;

pub use core::prompt_caching::PromptCacheConfig;

pub use core::prompt_caching::PromptOptimizer;

pub use core::timeout_detector::TimeoutDetector;

pub use gemini::Content;

pub use gemini::FunctionDeclaration;

pub use gemini::Part;

pub use llm::AnyClient;

pub use llm::make_client;

pub use markdown_storage::MarkdownStorage;

pub use markdown_storage::ProjectData;

pub use markdown_storage::ProjectStorage;

pub use markdown_storage::SimpleKVStorage;

pub use project::SimpleCache;

pub use project::SimpleProjectManager;

pub use prompts::generate_lightweight_instruction;

pub use prompts::generate_specialized_instruction;

pub use prompts::generate_system_instruction;

pub use simple_indexer::SimpleIndexer;

pub use tool_policy::ToolPolicy;

pub use tool_policy::ToolPolicyManager;

pub use tools::advanced_search::AdvancedSearchTool;

pub use tools::advanced_search::SearchOptions;

pub use tools::grep_search::GrepSearchManager;

pub use tools::tree_sitter::TreeSitterAnalyzer;

pub use tools::ToolRegistration;

pub use tools::ToolRegistry;

pub use tools::build_function_declarations;

pub use tools::build_function_declarations_for_level;

pub use tools::build_function_declarations_with_mode;

pub use ui::diff_renderer::DiffRenderer;

pub use utils::dot_config::CacheConfig;

pub use utils::dot_config::DotConfig;

pub use utils::dot_config::DotManager;

pub use utils::dot_config::ProviderConfigs;

pub use utils::dot_config::UiConfig;

pub use utils::dot_config::UserPreferences;

pub use utils::dot_config::WorkspaceTrustLevel;

pub use utils::dot_config::WorkspaceTrustRecord;

pub use utils::dot_config::WorkspaceTrustStore;

pub use utils::dot_config::initialize_dot_folder;

pub use utils::dot_config::load_user_config;

pub use utils::dot_config::save_user_config;

pub use utils::dot_config::update_theme_preference;

pub use utils::vtcodegitignore::initialize_vtcode_gitignore;

Modules

bash_runner

Simple bash-like command runner

cli

Command-line interface module

code

commands

Command implementations for different agent workflows

config

Configuration Management System

constants

Constants used throughout the application

core

Core Agent Architecture

gemini

Gemini API client with modular architecture

llm

LLM Integration Layer

markdown_storage

Simple markdown-based storage system

mcp_client

MCP Client implementation

models

Model definitions and constants

project

Simple project management using markdown storage

project_doc

prompts

System prompt generation with modular architecture

safety

Safety validation utilities

simple_indexer

Simple file indexer using regex and markdown storage

tool_policy

Tool policy management system

tools

Tool System Architecture

types

Type definitions used throughout the application

ui

User interface utilities and shared UI components

utils

Utility Functions and Helpers