# 01 — Caveman v2: current design (https://jackin.tailrocks.com/research/context/tools/01-caveman-design/) ## Summary [#summary] Caveman now combines an effective terse-output register with a broader input stack, but those mechanisms have different evidence, risks, and integration boundaries. Cutoff: **2026-08-12**. Current stable: [v2.0.0](https://github.com/JuliusBrussee/caveman/releases/tag/v2.0.0), released 2026-08-11. Caveman now contains **two distinct token interventions**: 1. an output-register skill that instructs the model to write terse prose; and 2. a local input-compression stack—engine, proxy, MCP server, CLI/SDK, recovery store, and optional representation transforms. Any current assessment must separate these mechanisms and their denominators. ## Question and scope [#question-and-scope] What do Caveman v2’s output register and input-compression stack each change, and what evidence supports either mechanism? ## Method [#method] The review fixes Caveman to v2.0.0 at the dossier cutoff, inspects upstream release material and source, separates output and input mechanisms, and grades release-specific outcome evidence independently. ## Findings [#findings] ### Current facts [#current-facts] | Field | Current value | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Repository | [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) | | Stable release | [v2.0.0](https://github.com/JuliusBrussee/caveman/releases/tag/v2.0.0) | | Adoption snapshot | 97,512 stars / 240 subscribers / 5,622 forks / 470 open issues and PRs | | Output layer | Caveman skill: lite/full/ultra and wenyan variants, with exact-content and clarity guards | | Input layer | Type-aware Go engine, proxy, MCP, SDK/CLI, CCR recovery, TOON and image/pixel options | | License | Skill, CLI, SDK, kit, evals, contracts, and catalog: MIT. Engine, proxy, MCP, shrink, cavemem-core, and platform: BSL-1.1 with delayed Apache-2.0 conversion | | Default safety posture | Parse/store/not-smaller failures pass through; exact originals recoverable by reference | Metadata source: [GitHub API](https://api.github.com/repos/JuliusBrussee/caveman). License boundaries: [LICENSING.md](https://github.com/JuliusBrussee/caveman/blob/v2.0.0/LICENSING.md). ### Current architecture [#current-architecture] ```text output path model decoder ── current Caveman skill ── shorter visible narration input path agent/tool payload ↓ local proxy / MCP / SDK ↓ type detection and routing ↓ JSON | logs | code | diff | search | HTML | tables | config | terminal | tool schemas | TOON | accessibility | repetition ↓ shorter-only check + CCR reference ↓ model context ``` The [engine documentation](https://github.com/JuliusBrussee/caveman/blob/v2.0.0/engine/README.md) describes fourteen routed compressor families. Compression is deterministic at this layer; the model does not summarize the payload. The store keeps exact originals behind compact references. An input cap and CCR capacity cap bound local resource use; parse errors, storage failures, and non-smaller outputs return the original content. The [proxy documentation](https://github.com/JuliusBrussee/caveman/blob/v2.0.0/proxy/README.md) describes a local base-URL swap and a record-only pass-through mode. A proxy remains an integrity boundary: it sees requests, may change cache geometry, and must preserve provider semantics. ### Current default stack [#current-default-stack] The v2 README presents `caveman claude` as the full wrapper: structured compression, TOON when smaller, MCP integration, and output shrinking. `--off` provides a pass-through control. Pixel mode re-encodes text as images only for gated models; it inherits model-legibility and modality risks similar to pxpipe. The output skill and input engine can be enabled independently. That separation is necessary for attribution: otherwise a lower total could come from shorter narration, smaller observations, changed agent behavior, or all three. ### Current evidence [#current-evidence] The current release ships a reproducible first-party [wrap benchmark](https://github.com/JuliusBrussee/caveman/blob/v2.0.0/docs/WRAP-BENCHMARK.md): six deterministic 60–95 KB tool-output fixtures, three repetitions per fixture, pinned agent/model, and exact-answer checks. The reported Caveman arm reduces provider-reported input 33.2% with 18/18 exact answers. This is useful fixture evidence, not an independent real-repository accepted-task benchmark. No independent end-to-end evaluation of **v2.0.0** was found by the cutoff. Results tied only to earlier skill releases are intentionally not carried into this current-only dossier. ## Implications for jackin❯ [#implications-for-jackin] ### Benefits [#benefits] * Only named tool with a first-class output skill **and** a newly integrated input engine. * Deterministic, content-typed compression instead of one generic summarizer. * Exact-original recovery through CCR. * Shorter-only and fail-closed pass-through guards reduce silent corruption risk. * Local proxy/engine path; multiple agent wrappers. * `--off` and record-only controls support an honest local A/B. ### Best fit [#best-fit] Use the **skill** when visible narration is the measured waste and terse language remains clear. Test the **v2 engine** when large JSON, logs, code/search output, terminal output, or tool schemas dominate fresh input and local recovery is required. Do not adopt the full stack merely because the two mechanisms share a repository. Enable one layer at a time, compare against `--off`, and require unchanged task acceptance plus successful raw recovery. ### Current verdict [#current-verdict] Caveman v2 is the largest architectural change in the named set. It is no longer accurately described as “a prompt, not a program.” The output skill remains the lightest intervention; the input engine is a new, broad competitor to Headroom and lean-ctx. Its current mechanism is credible and well-guarded, but the latest release has only first-party fixture evidence. Status: **promising, test locally, not yet proven generally**. Next: [02 — Headroom v0.34.0](/research/context/tools/02-headroom-design/). ## Limitations and unknowns [#limitations-and-unknowns] ### Costs and risks [#costs-and-risks] * v2.0.0 is one day old at the cutoff; operational maturity is unproven. * Product name hides two interventions; combined counters can obscure causality. * Engine-side code is BSL-1.1, not MIT/Apache today. Hosted resale has a commercial boundary. * Proxy/MCP/wrapper installation expands the trusted path and may overlap existing hooks. * CCR is local state with finite capacity and no eviction in the documented current engine; operators must monitor growth/failure behavior. * TOON and pixel transforms can change model comprehension even when byte recovery exists outside the active prompt. * The current fixture benchmark is vendor-owned and narrow. ## Sources [#sources] Evidence and repository references are cited inline beside the claims they support. ## Related work [#related-work] * [Token-optimization tools dossier](/research/context/tools/) * [Token-optimization techniques](/research/context/techniques/) * [Context engine](/research/context/engine/)