# vinhnx/vtcode architecture

> Architecture diagram of the GitHub repository vinhnx/vtcode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinhnx/vtcode
- Repository: https://github.com/vinhnx/vtcode

## Overview

##### Project type and purpose
- VT Code is a Rust-based, terminal-first “coding agent” CLI application with a built-in TUI, a modular library core (vtcode-core), a configuration subsystem (vtcode-config), tool abstractions (vtcode-tools, vtcode-bash-runner), and optional IDE integration via the Agent Client Protocol (ACP) through VS Code and Zed extensions.
- Its purpose is to provide AI-driven code intelligence (completion, analysis, refactoring, semantic search) by orchestrating LLM providers, enforcing security policies, managing context budgets, and hosting a rich TUI/IDE frontend.

##### File structure
- **Workspace root:** Cargo.toml enumerates many internal crates (vtcode, vtcode-core, vtcode-config, vtcode-tools, vtcode-commons, vtcode-acp-client, vtcode-bash-runner, etc.).
- **src/main.rs & src/lib.rs:** Entry points for the CLI.
- **src/cli/**: Each subcommand (ask, chat_tools, init, exec, etc.) lives here.
- **src/agent/**: The core agent run loop, context management, telemetry, tool pipelines, unified execution, and UI integration.
- **src/acp/**: ACP server/client for editor integrations.
- **src/process_hardening, src/sandbox, src/workspace_trust:** Security and sandboxing.
- **vtcode-core crate:** Contains the reusable core engine—LLM provider abstraction, prompt generation, context compression/curation, tool interfaces, exec policies, telemetry, and TUI widgets.
- **vtcode-config crate:** Configuration loader, schema, precedence, API-key management, hook registration.
- **vtcode-tools / vtcode-bash-runner crates:** Implement built-in tools and secure bash execution.
- **IDE/extensions:** vscode-extension and zed-extension talk to the ACP subsystem and embed the core as a library.
- **Scripts, docs, tests:** Build, CI, benchmarks, documentation, architecture guides.

##### README for additional insights
- **Architecture docs:** docs/ARCHITECTURE.md exists—likely high-level descriptions.
- **Key features call out:** Multi-provider AI, security model, TUI, ACP integration, lifecycle hooks, semantic search.
- **Deployment:** Single binary (vtcode) installed via Cargo or Homebrew, plus separate VS Code extension.

##### Essential elements, but don’t overcomplicate
- Break the system into high-level components first, then drill down into submodules if needed (e.g., within LLM Adapter, show each provider as a plugin).
- Sequence or data flow for the most critical mission: “User types → CLI → Agent Run Loop → LLM → Tool → UI.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interaction
    User["User"]:::external
    User -->|"types command"| CLI_Main

    %% CLI Frontend
    subgraph "CLI Frontend"
        direction TB
        CLI_Main["src/main.rs"]:::crate
        CLI_Lib["src/lib.rs"]:::crate
        CLI_Sub["src/cli/"]:::crate
    end
    CLI_Main --> CLI_Lib
    CLI_Lib --> CLI_Sub

    %% Configuration Layer
    Config["Configuration Layer\n(vtcode-config)"]:::config
    CLI_Lib -->|loads config| Config

    %% Agent Run Loop & Context Manager
    Agent["Agent Run Loop & Context Manager\n(src/agent/)"]:::crate
    CLI_Lib -->|invokes run loop| Agent

    %% Core Engine crate
    Core["Core Engine\n(vtcode-core)"]:::crate

    Agent --> Core

    %% LLM Provider Abstraction
    LLM["LLM Provider Abstraction\n(vtcode-core/src/llm/)"]:::crate
    Agent -->|Generate prompt| LLM
    LLM -->|calls| ExternalLLM

    %% External LLM APIs
    ExternalLLM["External LLM APIs"]:::external

    %% Tool Pipeline
    subgraph "Tool Pipeline"
        direction TB
        Tools["Built-in Tools\n(vtcode-tools)"]:::crate
        Bash["Bash Runner\n(vtcode-bash-runner)"]:::crate
    end
    Agent -->|invoke tool| Tools
    Agent -->|invoke bash| Bash

    %% External System
    FileSys["File System / Git / Network"]:::external
    Tools --> FileSys
    Bash --> FileSys

    %% Security & Sandbox
    Security["Security & Sandbox\n(src/process_hardening.rs,\nsrc/workspace_trust.rs)"]:::security
    Agent -->|validate| Security
    Security -->|enforce sandbox| SandboxCore

    SandboxCore["In-Core Sandbox\n(vtcode-core/src/sandbox/)"]:::crate

    %% Telemetry & Logging
    Telemetry["Telemetry & Logging\n(vtcode-commons/src/telemetry.rs)"]:::crate
    Agent -->|log events| Telemetry

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        TUI["TUI (terminal)\n(vtcode-core/src/ui/tui/)"]:::ui
        ACP_Server["ACP Server\n(src/acp/)"]:::crate
    end
    Core -->|render UI| TUI
    Agent -->|UI events| TUI
    Core --> ACP_Server
    ACP_Server --> VSCodeExt
    ACP_Server --> ZedExt

    %% IDE Extensions
    VSCodeExt["VSCode Extension"]:::ui
    ZedExt["Zed Extension"]:::ui

    %% Legend
    subgraph Legend
        direction TB
        A["Blue = Rust crates/modules"]:::crate
        B["Green = External services/APIs"]:::external
        C["Yellow = UI components"]:::ui
        D["Red = Security/Sandbox layer"]:::security
        E["Gray dashed = Configuration"]:::config
    end

    %% Click Events
    click CLI_Main "https://github.com/vinhnx/vtcode/blob/main/src/main.rs"
    click CLI_Lib "https://github.com/vinhnx/vtcode/blob/main/src/lib.rs"
    click CLI_Sub "https://github.com/vinhnx/vtcode/tree/main/src/cli/"
    click Config "https://github.com/vinhnx/vtcode/tree/main/vtcode-config/src/"
    click Agent "https://github.com/vinhnx/vtcode/tree/main/src/agent/"
    click Core "https://github.com/vinhnx/vtcode/tree/main/vtcode-core/src/"
    click LLM "https://github.com/vinhnx/vtcode/tree/main/vtcode-core/src/llm/"
    click Tools "https://github.com/vinhnx/vtcode/tree/main/vtcode-tools/src/"
    click Bash "https://github.com/vinhnx/vtcode/tree/main/vtcode-bash-runner/src/"
    click Telemetry "https://github.com/vinhnx/vtcode/blob/main/vtcode-commons/src/telemetry.rs"
    click SandboxCore "https://github.com/vinhnx/vtcode/tree/main/vtcode-core/src/sandbox/"
    click TUI "https://github.com/vinhnx/vtcode/tree/main/vtcode-core/src/ui/tui/"
    click ACP_Server "https://github.com/vinhnx/vtcode/tree/main/src/acp/"
    click VSCodeExt "https://github.com/vinhnx/vtcode/tree/main/vscode-extension/"
    click ZedExt "https://github.com/vinhnx/vtcode/tree/main/zed-extension/"

    %% Styles
    classDef crate fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ui fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef security fill:#FFCCCB,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
