# 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, 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, 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)