DocsCompression engineEngine CLI

Engine CLI

caveman-engine is the standalone binary that wraps the compression engine. It compresses, detects, recovers, reports stats, and runs the local quality gate. Everything it prints is inferred, and on any problem it forwards the original bytes unchanged.

This is the binary the cave CLI, and other tools, shell out to. It builds from source — there's no published package yet.

Build

terminal

go build -o ./bin/caveman-engine ./public/engine/cmd/caveman-engine

That uses the public engine source in this repo. For Python and JS/TS code compression, build with cgo enabled so tree-sitter is available. A cgo-free build still compresses Go plus non-code content types.

From source, for now

There is no npm, pip, Docker, or Homebrew package for the engine. Build it from source as shown. The only one-line install in the family today is the caveman skill.

Verbs

`compress`

Reads stdin, writes the compressed payload to stdout, and writes the JSON report (ratio, basis, recovery handle) to stderr — so stdout stays a clean payload you can pipe.

terminal

caveman-engine compress < tool-output.json > compressed.txt
# stderr:
# {"content_type":"json","tokens_before":16098,"tokens_after":1091,
#  "ratio":0.93,"basis":"inferred","recovery_handle":"..."}

Detection is automatic. To force a content type — including the forced-only toolschema and toon compressors that detection never routes to — pass --type:

terminal

caveman-engine compress --type toon < table.json > compressed.txt
caveman-engine compress --type auto < payload          # explicit auto-detect

Honesty rule

compress is byte-safe. On a parse problem, an incompressible payload, or no recovery store, it forwards the original bytes unchanged and reports inferred. It never claims a verified saving and never re-projects a ratio to a month.

`detect`

Prints the detected content type of stdin and nothing else. It needs no recovery store. Low-confidence input falls through to text.

terminal

caveman-engine detect < payload
# json

The result is one of json, diff, code, log, search-result, or text. detect never returns toolschema or toon — those are forced-only.

`retrieve <handle>`

Prints the byte-exact original for a recovery handle from a prior compress. This is the recoverable half of the lossy compressors: nothing is destroyed.

terminal

caveman-engine retrieve 7f3c... > original.json

An unknown handle is an error, not a silent empty result.

`stats`

Prints aggregate compression stats as JSON — totals and a per-content-type breakdown, all inferred.

terminal

caveman-engine stats
# { "totals": { ... }, "by_content_type": { "json": { ... } } }

`evals run`

Runs the local eval harness against embedded fixtures and prints the report as JSON. It is the quality gate: any fixture or grader failure is a non-zero exit, so it drops straight into CI.

terminal

caveman-engine evals run || echo "quality gate failed"

Fail closed

The gate fails closed. A failing fixture, or an unknown grader, exits non-zero — it never passes by default. That's the same instinct as the rest of the engine: when in doubt, refuse rather than claim.

At a glance

Verb	Reads	Writes	Notes
`compress`	stdin	payload → stdout, report → stderr	`--type <content-type>` to force; `inferred`
`detect`	stdin	content type → stdout	no store needed
`retrieve <handle>`	—	byte-exact original → stdout	recovers a prior compress
`stats`	—	aggregate stats (JSON) → stdout	`inferred`
`evals run`	—	report (JSON) → stdout	non-zero exit on any failure