Quickstart
Start with the skill if you only want shorter replies. Build the engine and proxy if you want local input-side compression and spend metering. Both paths are local; provider keys stay with you.
What's installable today
The only published install here is the caveman skill. The engine, proxy, CLI, and SDKs build from source. The commands below use repo paths that exist in this codebase.
1 — The skill (works now)
The skill teaches supported agents to answer in terse, fragment-based language. It changes output style only; code, paths, and identifiers stay exact.
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bashThat handles replies. The engine and proxy below handle what goes into the model.
2 — Build the engine and proxy
Build the two Go binaries from this repo. You need the pinned Go toolchain from .tool-versions.
# the content-aware compression engine
go build -o ./bin/caveman-engine ./public/engine/cmd/caveman-engine
# the byte-safe reverse proxy
go build -o ./bin/caveman-proxy ./public/proxy/cmd/caveman-proxyFull code compression needs cgo
Pure-Go builds compress Go source only. Build with cgo enabled to use tree-sitter for Python and JS/TS. JSON, logs, diffs, search results, and text use the same compressors either way.
3 — Compress something
Pipe any tool-output JSON, build log, or diff into the engine. The compressed payload goes to stdout; an inferred report goes to stderr.
echo '{"items":[{"id":1,"status":"ok"},{"id":2,"status":"ok"},{"id":3,"status":"ok"}]}' \
| ./bin/caveman-engine compressOn a real tool-output sample the engine turns sixteen thousand tokens into about eleven hundred:
16,0981,091tok−93%inferredIf compression emits a recovery handle, the original was stored first and caveman-engine retrieve <handle> returns it byte-for-byte. See recoverable compression.
4 — Put an agent behind the proxy
The proxy is a base-URL swap. Start it, then point an agent's provider base URL at 127.0.0.1:8787.
Start the proxy
Bring your own provider key. The proxy serves on 127.0.0.1:8787 and records local per-request spend to ~/.caveman/caveman.db.
ANTHROPIC_API_KEY=sk-ant-… ./bin/caveman-proxyPoint your agent at it
For an Anthropic-speaking agent, that's one environment variable:
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
claude # or codex, gemini, opencode, aider…The cave CLI automates this. caveman start launches the proxy; caveman wrap claude starts a wrapped agent with the right base URL.
Read your spend
Read local spend summary:
./bin/caveman-proxy statsHonesty rule
Default record mode is pass-through. compress mode only runs when explicitly enabled and falls back to the original bytes on any problem. Local spend and compression output are inferred, never verified, and not projected into monthly savings.