caveman-compress

Compress natural language memory files into shorter caveman format to reduce input tokens.

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/bittlinkm/claude-setup --skill caveman-compress-bittlinkm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: caveman-compress
Source: https://github.com/bittlinkm/claude-setup/tree/main/skills-disabled/caveman-compress
Command: npx skills add https://github.com/bittlinkm/claude-setup --skill caveman-compress-bittlinkm

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires anthropic, tiktoken, and includes scripts (resource) components.

What problem does it solve? Large project memory files like CLAUDE.md, todos, and preferences are loaded on every session start, repeatedly consuming input tokens. This Skill compresses those natural language files into a shorter caveman-style format while preserving code, URLs, paths, and structure, cutting repeated token costs. ## Core Features & Use Cases - Token-reducing compression: Rewrites prose by removing filler, hedging, and redundancy while preserving code blocks, inline code, URLs, file paths, headings, and tables exactly. - Validated in-place overwrite: Validates headings, code blocks, URLs, paths, and inline code after compression, applies targeted fixes with up to 2 retries, and restores the original on failure. - Safe backups: Stores the human-readable original as FILE.original.md in an out-of-tree data directory so skill auto-loaders never re-ingest it. - Use Case: Run it on a 1,000-token CLAUDE.md once, and every subsequent session loads the compressed version, saving roughly 46% of those repeated input tokens based on benchmarked fixtures. ## Quick Start Ask the assistant to run /caveman-compress on your CLAUDE.md file to compress it and create a backup of the original.

Frequently Asked Questions about caveman-compress

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compress a CLAUDE.md file to save tokens?

Run /caveman-compress followed by the file path, such as /caveman-compress CLAUDE.md. The skill compresses the prose in place and saves the original as a .original.md backup in an out-of-tree data directory.

What file types can be compressed with caveman-compress?

It compresses natural language files with .md, .txt, .rst, .typ, .typst, and .tex extensions, plus extensionless prose files. Code and config files like .py, .js, .json, and .yaml are skipped, as are .original.md backups.

Does compression preserve code blocks and URLs?

Yes. Fenced and indented code blocks, inline backtick code, URLs, file paths, commands, and headings are preserved exactly. A validator compares these elements between original and compressed output and triggers targeted fixes if anything changed.

Where is the original file backed up after compression?

Backups go to $XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/ on macOS and Linux, or %LOCALAPPDATA%\caveman-compress\backups\ on Windows. Keeping them out of the source tree prevents skill auto-loaders from re-ingesting the backup.

Why does caveman-compress refuse to compress some files?

It refuses files over 500KB, non-UTF-8 files, empty files, and files whose names suggest secrets or credentials such as .env, credentials, or id_rsa. Compression sends content to the Anthropic API, so sensitive files are blocked before any data leaves the machine.

What happens if validation fails after compression?

The skill sends only the specific validation errors back to the model for a targeted fix, retrying up to 2 times without recompressing. If it still fails, the original file is restored and the backup is removed.