This manual explains the public Caveman repository from installation through runtime behavior. It covers the files and interfaces that users can inspect in this repository. Hosted-service implementation details are outside its scope.
- Product model: what each Caveman layer does
- Architecture: request path, local processes, storage, and failure behavior
- Install and update: skill-only and local runtime installs
- CLI reference: command groups and output contracts
- Configuration: capability keys, local files, environment variables, and precedence
- Agent wrapping: supported agents, routing, recovery requirements, and profile format
- Compression Engine: detection, compressors, safety classes, token counts, and pass-through rules
- Context recovery: CCR handles, storage, retrieval, and retention limits
- Local proxy and providers: routes, credentials, usage parsing, and network boundaries
- TOON and Pixel: structured-data and image transforms
- Cache planner and rewriter: provider prompt caching and gated trajectory rewriting
- Skills, hooks, and plugins: response style, Claude Code hooks, opencode integration, extension behavior, and compressed subagents
- Memory, MCP, browser, and shrink: durable memory, five recovery tools, accessibility snapshots, command output, and tool catalogs
- Exploration and delegation: read-only repository search, compact return contracts, and delegation limits
- SDKs and packages: TypeScript, Python, Agent SDK, schemas, graders, React kit, Mastra, and provider catalog
- Accounting and evidence:
inferred, provider-reported, benchmark, andverifiedlabels - Security and privacy: data flows and secrets; local files; SSRF controls; binary verification
- Testing and benchmarks: local gates, benchmark boundaries, and reproducibility
- Extending Caveman: agent profiles, compressors, providers, schemas, and prices
- Glossary: every Caveman-specific term used by this manual
Package READMEs remain the narrow API references. This manual supplies the cross-component model and links to those references where details belong.