How juliusbrussee/caveman-code works
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: agent-session-runtime.ts Agent runtime · cli.ts caveman CLI · index.ts AI boundary · interactive-mode.ts Interactive TUI
Components 22
Clients
User-facing terminal, daemon, web, and SDK entrypoints
- caveman CLI · Main terminal entrypoint and mode dispatcher
packages/coding-agent/src/cli.ts - Interactive TUI · Terminal session loop and render plumbing
packages/coding-agent/src/modes/interactive/interactive-mode.ts - Other modes · Print, exec, JSON/RPC, attach, and serve surfaces
packages/coding-agent/src/modes/print-mode.ts - Daemon · Persistent session server for attach and remote control
packages/coding-agent/src/core/daemon/server.ts - Web UI · Browser-based client with sandboxed artifacts and storage
packages/web-ui/src/index.ts - SDK · Programmatic client boundary for session and daemon protocol
packages/sdk/src/client.ts
Runtime
Core agent orchestration, state, tools, and extensions
- Agent runtime · Session loop, prompt assembly, tool routing, and turn control
packages/coding-agent/src/core/agent-session-runtime.ts - Session state · Session lifecycle, history, branching, resume, and replay
packages/coding-agent/src/core/session-manager.ts - Tool layer · Filesystem, shell, search, edit, task, memory, and MCP tools
packages/coding-agent/src/core/tools/index.ts - Context reduction · Repo maps, truncation, deduplication, and output shaping
packages/coding-agent/src/core/cave-structured-compression.ts - Memory · Semantic memory and file-backed memory bridge
packages/coding-agent/src/core/memory-bridge.ts - Checkpoints · Shadow-git snapshots and rollback coordination
packages/coding-agent/src/core/slash-commands/checkpoint.ts - Extensions · Dynamic extensions that alter prompts, tools, or rendering
packages/coding-agent/src/core/extensions/loader.ts - Hooks · Observer-style integrations for policy and automation
packages/coding-agent/src/core/hooks/index.ts - Skills & commands · 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 · Streaming, message transforms, auth, and model selection
packages/ai/src/index.ts - Providers · Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, and compatible endpoints
packages/ai/src/providers/register-builtins.ts - Auth & registry · OAuth, API key resolution, and model metadata loading
packages/ai/src/oauth.ts
Support
Shared UI, docs, packaging, and evaluation tooling
- TUI package · Reusable terminal UI widgets, editors, lists, and overlays
packages/tui/src/tui.ts - Docs · VitePress guides, references, and API docs
docs/index.md - Research/evals · Benchmarks, traces, and performance validation tooling
research/README.md - Packaging · Installers, Docker, Homebrew, CI, and release scripts
Dockerfile
Connections 25
- 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