# juliusbrussee/caveman-code architecture

> Architecture diagram of the GitHub repository juliusbrussee/caveman-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juliusbrussee/caveman-code
- Repository: https://github.com/juliusbrussee/caveman-code

## Overview

1. **What this repo is**
   - A TypeScript monorepo for a terminal-first AI coding agent.
   - The main product is the `caveman` CLI/TUI, but the repo also ships an SDK, a web UI, a daemon/server mode, and evaluation/research tooling.

2. **Top-level architecture**
   - The system splits into:
     - **User-facing clients**: terminal TUI, print/JSON/RPC modes, daemon attach, web UI.
     - **Agent runtime**: session management, prompt loop, tool execution, compaction, memory, checkpoints.
     - **Model/provider layer**: multi-provider model registry, OAuth/API-key auth, message transformation, streaming.
     - **Supporting packages**: shared SDK, TUI primitives, markdown preview, docs, benchmarks, packaging.

3. **Main execution path**
   - User prompt enters via `packages/coding-agent` CLI.
   - The session/runtime builds context from the working directory, session history, memory, repo map, skills/commands, and tool state.
   - The agent sends a structured request through `packages/ai` to a selected provider.
   - Model output can trigger tool calls; tool results are fed back into the next turn.
   - The loop continues until completion, compaction, or user interruption.

4. **Core engine: `packages/coding-agent`**
   - This is the orchestration layer for the whole product.
   - It owns:
     - session lifecycle and persistence,
     - interactive and non-interactive modes,
     - slash commands,
     - hooks,
     - recipes,
     - plugins,
     - subagents,
     - checkpoints/rollback,
     - goal/autopilot loop,
     - plan mode and architect/editor model split.
   - It is the package most of the CLI, UI, and session behavior hang off.

5. **Model and provider subsystem: `packages/ai`**
   - This package abstracts model providers and API differences.
   - It includes provider adapters for Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, and other compatible endpoints.
   - It also handles:
     - OAuth flows,
     - API-key resolution,
     - streaming event parsing,
     - message transformation between provider formats,
     - token/cache policy support,
     - model registry/metadata loading.
   - Diagram-wise, this is the boundary between the agent and external LLM services.

6. **Tooling and file/system interaction**
   - The agent’s tool layer is centered in `packages/coding-agent/src/core/tools` and related helpers.
   - Tools cover filesystem reads/writes, shell execution, grep/find/ls, edit-by-diff, task/subagent execution, memory operations, and MCP bridging.
   - Tool results are intentionally compressed/deduplicated before re-entering the model context.
   - External boundaries here are the local repo filesystem, shell processes, Git, and any attached MCP servers.

7. **Session state, persistence, and recovery**
   - Sessions are stored as JSONL history and organized by working directory.
   - The repo supports branching, resume, tree navigation, and replay.
   - Checkpoints use Git-like semantics with shadow-git/snapshot logic so code changes and conversation history can be rolled back together.
   - A daemon mode persists sessions separately so they survive terminal disconnects.

8. **Context reduction and memory**
   - This repo treats context as a first-class subsystem.
   - It has:
     - repo map generation,
     - tool output truncation/budgeting,
     - read deduplication,
     - caveman-style terse model responses,
     - optional RTK compression for shell output,
     - persistent semantic memory via `cavemem`.
   - The main data flow is: raw repo/tool data → compressed/filtered context → model prompt.

9. **Extensibility boundaries**
   - Extensions and plugins are loaded dynamically and can alter prompts, tools, rendering, or runtime behavior.
   - Claude Code-compatible surfaces are supported for skills, commands, agents, settings, and MCP config.
   - MCP support is a major integration boundary: the agent can act as an MCP client and also expose itself as an MCP server.
   - Hooks are observer-style integrations used for automation and policy, not for replacing the core loop.

10. **User interfaces**
   - The primary UI is the terminal TUI in `packages/tui` plus `packages/coding-agent/src/modes/interactive`.
   - Non-interactive surfaces include print mode, exec mode, JSON/RPC mode, and CLI subcommands.
   - `packages/web-ui` is a separate browser client that reuses the agent protocol and tool/rendering concepts, with sandboxed runtime providers for artifacts, attachments, console, and file downloads.
   - `packages/sdk` is the thin client boundary for programmatic access to the daemon/session protocol.

11. **Operational and distribution layer**
   - The repo includes installers, a Docker image, a Homebrew formula, and CI workflows for build/test/release.
   - Docs are built separately with VitePress.
   - Research/evals live under `research/` and are not part of the runtime, but they validate the token-compression and agent performance claims.

12. **How to diagram it**
   - Draw the center as: **CLI/TUI or daemon client → coding-agent runtime → ai provider layer → external model APIs**.
   - Around that center, show side boundaries for:
     - **filesystem/git/shell tools**,
     - **MCP servers**,
     - **session storage/checkpoints**,
     - **memory service**,
     - **extensions/plugins/hooks**.
   - Treat `packages/agent`, `packages/ai`, `packages/tui`, `packages/web-ui`, and `packages/sdk` as the main architectural packages, with `packages/coding-agent` as the orchestration core.

Main entry points: [`packages/coding-agent/src/core/agent-session-runtime.ts`](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/agent-session-runtime.ts) (Agent runtime), [`packages/coding-agent/src/cli.ts`](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/cli.ts) (caveman CLI), [`packages/ai/src/index.ts`](https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/index.ts) (AI boundary), [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts) (Interactive TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_clients["Clients"]
  node_node_cli["caveman CLI<br/>entrypoint<br/>[cli.ts]"]
  node_node_interactive["Interactive TUI<br/>tui runtime"]
  node_node_noninteractive["Other modes<br/>cli modes<br/>[print-mode.ts]"]
  node_node_daemon[("Daemon<br/>server mode<br/>[server.ts]")]
  node_node_web_ui["Web UI<br/>browser client<br/>[index.ts]"]
  node_node_sdk["SDK<br/>client lib<br/>[client.ts]"]
end

subgraph group_group_runtime["Runtime"]
  node_node_runtime{{"Agent runtime<br/>orchestrator"}}
  node_node_session[("Session state<br/>persistence<br/>[session-manager.ts]")]
  node_node_tools["Tool layer<br/>tools<br/>[index.ts]"]
  node_node_context["Context reduction<br/>compression"]
  node_node_memory[("Memory<br/>[memory-bridge.ts]")]
  node_node_checkpoints[("Checkpoints<br/>rollback<br/>[checkpoint.ts]")]
  node_node_extensions["Extensions<br/>plugin system<br/>[loader.ts]"]
  node_node_hooks["Hooks<br/>automation<br/>[index.ts]"]
  node_node_assets["Skills & commands<br/>prompt assets<br/>[skills.ts]"]
end

subgraph group_group_models["Model layer"]
  node_node_ai{{"AI boundary<br/>provider abstraction<br/>[index.ts]"}}
  node_node_providers["Providers<br/>adapters"]
  node_node_registry["Auth & registry<br/>metadata<br/>[oauth.ts]"]
end

subgraph group_group_support["Support"]
  node_node_tui_pkg["TUI package<br/>ui primitives<br/>[tui.ts]"]
  node_node_docs["Docs<br/>documentation<br/>[index.md]"]
  node_node_evals["Research/evals<br/>evaluation<br/>[README.md]"]
  node_node_packaging["Packaging<br/>distribution"]
end

node_node_cli -->|"launches"| node_node_interactive
node_node_cli -->|"dispatches"| node_node_noninteractive
node_node_cli -->|"serves"| node_node_daemon
node_node_cli -.->|"shares protocol"| node_node_sdk
node_node_interactive -->|"drives"| node_node_runtime
node_node_noninteractive -->|"executes"| node_node_runtime
node_node_daemon -->|"persists"| node_node_session
node_node_sdk -->|"connects"| node_node_daemon
node_node_runtime -->|"reads/writes"| node_node_session
node_node_runtime -->|"invokes"| node_node_tools
node_node_runtime -->|"compresses"| node_node_context
node_node_runtime -->|"consults"| node_node_memory
node_node_runtime -->|"rolls back"| node_node_checkpoints
node_node_runtime -->|"loads"| node_node_extensions
node_node_runtime -.->|"notifies"| node_node_hooks
node_node_runtime -->|"assembles"| node_node_assets
node_node_runtime -->|"queries"| node_node_ai
node_node_ai -->|"routes to"| node_node_providers
node_node_ai -->|"resolves"| node_node_registry
node_node_tui_pkg -.->|"renders"| node_node_interactive
node_node_web_ui -.->|"mirrors"| node_node_runtime
node_node_web_ui -.->|"uses"| node_node_sdk
node_node_docs -.->|"documents"| node_node_cli
node_node_evals -.->|"validates"| node_node_context
node_node_packaging -.->|"ships"| node_node_cli

click node_node_cli "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/cli.ts"
click node_node_interactive "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts"
click node_node_noninteractive "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/modes/print-mode.ts"
click node_node_daemon "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/daemon/server.ts"
click node_node_web_ui "https://github.com/juliusbrussee/caveman-code/blob/main/packages/web-ui/src/index.ts"
click node_node_sdk "https://github.com/juliusbrussee/caveman-code/blob/main/packages/sdk/src/client.ts"
click node_node_runtime "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/agent-session-runtime.ts"
click node_node_session "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/session-manager.ts"
click node_node_tools "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/tools/index.ts"
click node_node_context "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/cave-structured-compression.ts"
click node_node_memory "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/memory-bridge.ts"
click node_node_checkpoints "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/slash-commands/checkpoint.ts"
click node_node_extensions "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/extensions/loader.ts"
click node_node_hooks "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/hooks/index.ts"
click node_node_assets "https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/skills.ts"
click node_node_ai "https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/index.ts"
click node_node_providers "https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/providers/register-builtins.ts"
click node_node_registry "https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/oauth.ts"
click node_node_tui_pkg "https://github.com/juliusbrussee/caveman-code/blob/main/packages/tui/src/tui.ts"
click node_node_docs "https://github.com/juliusbrussee/caveman-code/blob/main/docs/index.md"
click node_node_evals "https://github.com/juliusbrussee/caveman-code/blob/main/research/README.md"
click node_node_packaging "https://github.com/juliusbrussee/caveman-code/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_interactive,node_node_noninteractive,node_node_daemon,node_node_web_ui,node_node_sdk toneBlue
class node_node_runtime,node_node_session,node_node_tools,node_node_context,node_node_memory,node_node_checkpoints,node_node_extensions,node_node_hooks,node_node_assets toneAmber
class node_node_ai,node_node_providers,node_node_registry toneMint
class node_node_tui_pkg,node_node_docs,node_node_evals,node_node_packaging toneRose
```

## Components

### Clients

User-facing terminal, daemon, web, and SDK entrypoints

- [caveman CLI](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/cli.ts): entrypoint · Main terminal entrypoint and mode dispatcher · `packages/coding-agent/src/cli.ts`
- [Interactive TUI](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts): tui runtime · Terminal session loop and render plumbing · `packages/coding-agent/src/modes/interactive/interactive-mode.ts`
- [Other modes](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/modes/print-mode.ts): cli modes · Print, exec, JSON/RPC, attach, and serve surfaces · `packages/coding-agent/src/modes/print-mode.ts`
- [Daemon](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/daemon/server.ts): server mode · Persistent session server for attach and remote control · `packages/coding-agent/src/core/daemon/server.ts`
- [Web UI](https://github.com/juliusbrussee/caveman-code/blob/main/packages/web-ui/src/index.ts): browser client · Browser-based client with sandboxed artifacts and storage · `packages/web-ui/src/index.ts`
- [SDK](https://github.com/juliusbrussee/caveman-code/blob/main/packages/sdk/src/client.ts): client lib · Programmatic client boundary for session and daemon protocol · `packages/sdk/src/client.ts`

### Runtime

Core agent orchestration, state, tools, and extensions

- [Agent runtime](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/agent-session-runtime.ts): orchestrator · Session loop, prompt assembly, tool routing, and turn control · `packages/coding-agent/src/core/agent-session-runtime.ts`
- [Session state](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/session-manager.ts): persistence · Session lifecycle, history, branching, resume, and replay · `packages/coding-agent/src/core/session-manager.ts`
- [Tool layer](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/tools/index.ts): tools · Filesystem, shell, search, edit, task, memory, and MCP tools · `packages/coding-agent/src/core/tools/index.ts`
- [Context reduction](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/cave-structured-compression.ts): compression · Repo maps, truncation, deduplication, and output shaping · `packages/coding-agent/src/core/cave-structured-compression.ts`
- [Memory](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/memory-bridge.ts): persistent memory · Semantic memory and file-backed memory bridge · `packages/coding-agent/src/core/memory-bridge.ts`
- [Checkpoints](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/slash-commands/checkpoint.ts): rollback · Shadow-git snapshots and rollback coordination · `packages/coding-agent/src/core/slash-commands/checkpoint.ts`
- [Extensions](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/extensions/loader.ts): plugin system · Dynamic extensions that alter prompts, tools, or rendering · `packages/coding-agent/src/core/extensions/loader.ts`
- [Hooks](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/hooks/index.ts): automation · Observer-style integrations for policy and automation · `packages/coding-agent/src/core/hooks/index.ts`
- [Skills & commands](https://github.com/juliusbrussee/caveman-code/blob/main/packages/coding-agent/src/core/skills.ts): prompt assets · Claude-compatible skills, slash commands, recipes, and templates · `packages/coding-agent/src/core/skills.ts`

### Model layer

Provider abstraction, auth, streaming, and model metadata

- [AI boundary](https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/index.ts): provider abstraction · Streaming, message transforms, auth, and model selection · `packages/ai/src/index.ts`
- [Providers](https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/providers/register-builtins.ts): adapters · Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, and compatible endpoints · `packages/ai/src/providers/register-builtins.ts`
- [Auth & registry](https://github.com/juliusbrussee/caveman-code/blob/main/packages/ai/src/oauth.ts): metadata · OAuth, API key resolution, and model metadata loading · `packages/ai/src/oauth.ts`

### Support

Shared UI, docs, packaging, and evaluation tooling

- [TUI package](https://github.com/juliusbrussee/caveman-code/blob/main/packages/tui/src/tui.ts): ui primitives · Reusable terminal UI widgets, editors, lists, and overlays · `packages/tui/src/tui.ts`
- [Docs](https://github.com/juliusbrussee/caveman-code/blob/main/docs/index.md): documentation · VitePress guides, references, and API docs · `docs/index.md`
- [Research/evals](https://github.com/juliusbrussee/caveman-code/blob/main/research/README.md): evaluation · Benchmarks, traces, and performance validation tooling · `research/README.md`
- [Packaging](https://github.com/juliusbrussee/caveman-code/tree/main/Dockerfile): distribution · Installers, Docker, Homebrew, CI, and release scripts · `Dockerfile`

## Connections

- caveman CLI → Interactive TUI: launches · Routes terminal users into the interactive session UI
- caveman CLI → Other modes: dispatches · Selects non-interactive execution surfaces and subcommands
- caveman CLI → Daemon: serves · Starts or attaches to persistent daemon sessions
- caveman CLI → SDK: shares protocol · Exposes the same session protocol used by programmatic clients
- Interactive TUI → Agent runtime: drives · Feeds user input into the main agent loop
- Other modes → Agent runtime: executes · Runs the same runtime without the full TUI
- Daemon → Session state: persists · Keeps sessions alive across disconnects and restarts
- SDK → Daemon: connects · Client library for daemon and session protocol
- Agent runtime → Session state: reads/writes · Builds, updates, and resumes session state
- Agent runtime → Tool layer: invokes · Calls tools for filesystem, shell, search, edit, and MCP work
- Agent runtime → Context reduction: compresses · Reduces raw repo and tool output before model turns
- Agent runtime → Memory: consults · Pulls persistent memory into context and updates it
- Agent runtime → Checkpoints: rolls back · Coordinates snapshot and rollback semantics
- Agent runtime → Extensions: loads · Allows runtime customization through extensions
- Agent runtime → Hooks: notifies · Emits lifecycle events for automation and policy
- Agent runtime → Skills & commands: assembles · Builds prompt context from skills, commands, recipes, and templates
- Agent runtime → AI boundary: queries · Sends structured turns to model providers
- AI boundary → Providers: routes to · Selects provider-specific request and streaming adapters
- AI boundary → Auth & registry: resolves · Handles auth, API keys, and model metadata lookup
- TUI package → Interactive TUI: renders · Supplies reusable terminal widgets and input primitives
- Web UI → Agent runtime: mirrors · Browser client follows the same agent protocol and concepts
- Web UI → SDK: uses · Shares client-side session and storage patterns
- Docs → caveman CLI: documents · Explains workflows, modes, configuration, and runtime features
- Research/evals → Context reduction: validates · Benchmarks compression and agent performance claims
- Packaging → caveman CLI: ships · Builds installers, binaries, and release artifacts