# vtcode-core
Core library for VT Code — a Rust-based terminal coding agent.
`vtcode-core` powers the VT Code agent runtime. 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, Meta AI, Gemini,
OpenRouter, and Ollama (local), including automatic failover and spend controls.
- **Prompt Caching** — cross-provider 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** — LLM-native code analysis and navigation across all modern programming languages.
- **Bash Shell Safety** — `tree-sitter-bash` integration for critical command validation and security enforcement.
- **Tool System** — trait-driven registry for shell execution, file IO, search, and custom commands, with Tokio-powered
concurrency and PTY streaming.
- **Ownership-First Tool Bridging** — prefer native CGP wrappers and borrowed tool references; use `Arc<dyn Tool>`
bridges only when tools genuinely need shared ownership.
- **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 for comprehensive audit trails.
### 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, Meta AI, Gemini,
OpenRouter, and Ollama (local), 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**: LLM-native code analysis and navigation across all modern programming languages.
- **Bash Shell Safety**: tree-sitter-bash integration for critical command validation and security enforcement.
- **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 for comprehensive audit trails.
#### 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 and memory.
- `executor/`: async orchestration for tool invocations and streaming output.
- `core/prompt_caching`: cross-provider prompt caching system that leverages provider-specific caching mechanisms for
cost optimization and reduced latency.
#### Quickstart
```rust
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:
```rust
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](https://github.com/vinhnx/vtcode/blob/main/docs/guides/zed-acp.md), with a rendered summary
on [docs.rs](https://docs.rs/vtcode/latest/vtcode/#agent-client-protocol-acp).
##### 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.
VT Code Core Library
This crate provides the core functionality for the VT Code agent, including tool implementations, LLM integration, and
utility functions.
## Architecture Overview
| `config/` | Configuration loader, defaults, schema validation |
| `llm/` | Provider clients, request shaping, response handling |
| `tools/` | Built-in tool implementations and registration utilities |
| `context/` | Conversation management and memory |
| `exec/` | Async orchestration for tool invocations and streaming output |
| `core/prompt_caching` | Cross-provider prompt caching system |
| `mcp/` | Model Context Protocol client support |
| `safety/` | Workspace boundary enforcement and command safety |
## Public entrypoints
- `Agent` / `AgentRunner` — main agent runtime
- `VTCodeConfig` — configuration loader (`vtcode.toml` + environment overrides)
- `ToolRegistry` / `OptimizedToolRegistry` — tool registration and execution
- `AnyClient` / `make_client` — provider-agnostic LLM client factory
- `PromptCache` / `PromptOptimizer` — prompt caching primitives
- `ThreadManager` — thread lifecycle and event recording
## Usage
```rust,ignore
use vtcode_core::{Agent, VTCodeConfig};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = VTCodeConfig::load()?;
let agent = Agent::new(config).await?;
agent.run().await?;
Ok(())
}
```
## Feature flags
| `tui` (default) | Terminal UI via crossterm |
| `schema` | JSON Schema generation via `schemars` |
| `a2a-server` | Agent2Agent Protocol HTTP server |
| `anthropic-api` | Anthropic-compatible API server |
| `desktop-notifications` | Desktop notification support |
## API reference
See [docs.rs/vtcode-core](https://docs.rs/vtcode-core).
## Related docs
- [Architecture overview](../docs/ARCHITECTURE.md)