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