Architecture Overview

Caboose is a terminal-native AI coding agent built in Rust. It ships as a single binary with no runtime dependencies beyond a working terminal and network access, and runs on Linux, macOS, and Windows.

Layer Diagram

┌─────────────────────────────────────────────┐
│                 TUI Layer                    │
│  (widgets, input handling, layout)            │
├─────────────────────────────────────────────┤
│              App State Machine               │
│  (sessions, mode switching, tool approval)   │
├─────────────┬───────────────┬───────────────┤
│ Agent Loop  │  Tool Runner  │  Provider Hub │
│ (turns,     │  (file ops,   │  (Anthropic,  │
│  streaming, │   shell exec, │   OpenAI,     │
│  compaction)│   glob/grep)  │   Gemini ...) │
├─────────────┴───────────────┴───────────────┤
│            Persistence Layer                 │
│  (SQLite sessions, config, memory)           │
└─────────────────────────────────────────────┘

Major Subsystems

Subsystem	Responsibility
Agent Loop	Multi-turn conversation engine, streaming, compaction, cold storage, tool dispatch
Provider Hub	Unified provider interface, streaming HTTP for Anthropic, OpenAI, Gemini, OpenRouter, and more
Tool Runner	Tool registry and implementations: read, write, edit, glob, grep, shell, fetch
TUI	Layout, chat view, home screen, sidebar, dialogs, command palette, syntax highlighting, themes
Config	TOML config parsing, auth store, key management, preferences
Sessions	SQLite persistence for sessions, snapshot-based crash recovery
Memory	Persistent memory loading, full-text search index, automatic observation extraction
MCP	Model Context Protocol server lifecycle management
Skills	Built-in skills (11 total), file-based skill loading, resolution, creation
Safety	Command allow/deny policies, environment variable filtering

Key Design Decisions

No SDK dependencies. Every LLM provider is accessed through raw HTTP requests and server-sent event parsing. This eliminates version churn from vendor SDKs, keeps the dependency tree small, and gives Caboose full control over retry logic and streaming behavior.

Raw streaming everywhere. Provider responses arrive as SSE streams and are forwarded to the TUI for token-by-token rendering with no buffering delay.

SQLite as the single persistence backend. Sessions, memory search indexes, and snapshots all live in a single SQLite database. This avoids the complexity of multiple storage formats while keeping the application portable — no external database process is needed.

Single binary distribution. One executable with all assets compiled in. Install via Homebrew on macOS or download the binary directly.