caveman-compress

Caveman Compress

Purpose

Data leaves the machine. Compression sends the file's full text to the model provider that scripts/compress.py is configured for: the claude CLI, the Anthropic API, or an OpenAI-compatible endpoint. Files whose names look like secrets (.env, credentials, secrets, .netrc, …) are refused before they are read. Don't compress a file the provider shouldn't see.

Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as <filename>.original.md, but NOT beside the source file — it lives in an out-of-tree data dir ($XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/, or %LOCALAPPDATA%\caveman-compress\backups\<parent-dir-name>\ on Windows) so skill auto-loaders don't re-ingest it as a live file.

Trigger

/caveman-compress <filepath> or when user asks to compress a memory file.

Requires an explicit filepath. If the user pastes raw text instead of naming a file, do NOT improvise an inline compression — ask them for the filepath to compress, or offer to save the pasted text to a file first. Writing your own reasoning/commentary about the request into the compressed output (e.g. "User passed text directly, not a filepath...") is the exact failure this guards against — never let that leak into a saved file.

Process

1. The compression scripts live in scripts/ (adjacent to this SKILL.md). If the path is not immediately available, search for scripts/__main__.py next to this SKILL.md.

2. From the directory containing this SKILL.md, run:

python3 -m scripts <absolute_filepath>

3. The CLI will:

• detect file type (no tokens)
• call Claude to compress
• validate output (no tokens)
• if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
• retry up to 2 times
• if still failing after 2 retries: report error to user, leave original file untouched

4. Return result to user

Compression Rules

Remove

• Articles: a, an, the
• Filler: just, really, basically, actually, simply, essentially, generally
• Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
• Hedging: "it might be worth", "you could consider", "it would be good to"
• Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
• Connective fluff: "however", "furthermore", "additionally", "in addition"