mirror of
https://github.com/JuliusBrussee/caveman.git
synced 2026-09-14 18:02:35 +08:00
Julius Brussee
695703c0d5
- cache original base URLs per model, not per provider, so a same-provider model with its own endpoint stays direct (#973) - proxy publishes its named compat mounts in the run-state file; the pi extension routes a custom provider through /w/pi/compat/<name> only when a mount with that name and a matching host is published (#952, #970) - hostOf compares host:port so loopback relays on different ports differ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W2f7Lf7G9erA7YNn5SXPEj
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
- TOON and Pixel: structured-data and image transforms
- Cache planner and rewriter: provider prompt caching and gated trajectory rewriting
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, 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.