Caveman technical documentation

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.

Start here

• 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

Runtime

• 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
• Deploy the proxy for a team: shared VPC and cloud deployment, inbound token, containers, and manifests
• TOON and Pixel: structured-data and image transforms
• Cache planner: provider prompt caching
• Framework middleware: TypeScript and Python adapters that wrap one call in your own app; hosted guide at https://docs.caveman.so/docs/sdk/middleware

Agent-facing tools

• 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

Building on Caveman

• SDKs and packages: TypeScript and Python SDKs, shared contracts and schemas, provider catalog, and benchmark tooling
• caveman learn: local setup profiler, Setup Score, sinks, autopilot, and consent-gated fixes
• Accounting and evidence: inferred, provider-reported, benchmark, and verified labels
• 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.