01 — Caveman v2: current design

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, 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

What do Caveman v2’s output register and input-compression stack each change, and what evidence supports either mechanism?

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

Current facts

Metadata source: GitHub API. License boundaries: LICENSING.md.

Current architecture

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 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 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

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

The current release ships a reproducible first-party wrap benchmark: 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❯

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

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

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.

Limitations and unknowns

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

Evidence and repository references are cited inline beside the claims they support.

Related work

• Token-optimization tools dossier
• Token-optimization techniques
• Context engine