Local tools

Caveman ships local tools for recovery, memory, browser context, and large command output. They work without a Caveman account.

MCP server

Register recovery server with detected agents:

caveman tools mcp install

Run caveman tools mcp uninstall to remove registration. Direct server binary, caveman-mcp, communicates over standard input and output.

It exposes five tool classes:

Tool	Purpose
Compress	Reduce eligible context and return recovery reference
Retrieve	Fetch exact source for a recovery handle
Stats	Read local compression statistics
TOON encode	Encode supported structured input
TOON decode	Decode and validate TOON input

MCP transport is local process I/O, and host agent decides when tools can be called. Configure its tool permissions as narrowly as possible.

Cavemem

Cavemem stores durable project facts in SQLite and retrieves them with local BM25 text ranking.

Main operations:

caveman tools mem remember "fact"
caveman tools mem recall "query"
caveman tools mem supersede <id> "replacement"
caveman tools mem history <id>
caveman tools mem forget <id>

Recall returns current facts by default and has a default inferred-token budget of 2,000. Superseded history remains available for inspection. Recalled compact records can include recovery references to exact stored source.

Memory is local persistence, not model training. A remembered statement can be wrong or stale; source and supersession metadata help callers judge it.

Build standalone binary:

go build -o cavemem ./mem/cmd/cavemem

Browser bridge

Browser bridge attaches to Chrome through Chrome DevTools Protocol. It captures an accessibility-tree representation, filters it by query, compresses it, and returns actionable element references.

caveman tools browse https://example.com "pricing"
caveman tools browse act '<reference>' click
caveman tools browse eval 'document.title'
caveman tools browse recover '<handle>'
caveman tools browse close

Snapshots avoid screenshots when semantic structure is enough. Recovery keeps exact captured source available. Browser actions and JavaScript evaluation can change page or account state; host permission policy should distinguish read and write operations.

Build bridge:

go build ./browse/cmd/caveman-browse

Output shrinker

Output shrinker parses large command and tool results, keeps high-signal structure, and stores full source in CCR. It is useful for compiler logs, test output, diffs, search results, and terminal transcripts.

some-command | caveman tools shrink
caveman tools shrink -- go test ./...

Structural shrink input is capped at 32 MiB. CLI command capture uses a separate bounded limit, 8 MiB by default. Oversized input is rejected or handled by caller policy; it is not silently treated as complete.

Shrinker must preserve error class, exit status, relevant paths, and recovery handle. A short summary without those fields is not a safe replacement for debugging output.

Tool-catalog shrinker

caveman-shrink specializes in MCP and OpenAI-style tool catalogs. It keeps tool names, parameters, enums, required fields, defaults, constants, and $ref targets while removing annotations and shortening long descriptions. Description reduction remains lossy and can change tool selection.

cat tools.json | caveman-shrink > tools.min.json
caveman-shrink lint tools.json
caveman-shrink recover <handle> > tools.original.json

Input cap is 32 MiB. Malformed or non-winning input passes through. Exact source must be committed to CCR before compact catalog and handle are emitted.

Local storage

Local proxy and tools commonly use:

~/.caveman/caveman.db
~/.caveman/ccr.db
~/.caveman/mem/mem.db
~/.caveman/mem/ccr.db
~/.caveman/caveman.yaml
~/.caveman-cloud/config.json

Project overlays use ./.caveman/config.json. Back up or delete these files only with awareness that recovery handles and learned observations may stop resolving, along with local memory.