mirror of
https://github.com/JuliusBrussee/caveman.git
synced 2026-09-14 18:02:35 +08:00
Julius Brussee
d6c1cd39af
A foreign listener on 127.0.0.1:8787 used to get the banner but still receive the routed launch, which would send the operator's provider keys to a process caveman does not own (#945). Treat it like a gate mismatch and fall back to a direct launch. Also: Claude Code refuses Remote Control behind any non-first-party ANTHROPIC_BASE_URL, so `caveman claude remote-control` launches direct and the limitation is documented (#947); caveman-compress reads the first text block instead of content[0] so a leading tool_use block no longer crashes after a paid call (closes #932's report); hook checksum manifest regenerated after #794. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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.