caveman-compress Skill for Claude: Compress Memory Files

caveman-compress rewrites a memory file such as CLAUDE.md in short caveman prose to save input tokens, and keeps a backup.

Installs: 419.4K; on skills.sh
Stars: 116.7K; on GitHub
Files: 9; besides SKILL.md
Updated: Nov 2026; last repo commit

caveman-compress takes a file path, like /caveman-compress CLAUDE.md, and runs a bundled Python script that asks a model to rewrite the prose in shorter form. Code blocks, inline code, URLs, file paths, commands and version numbers are kept exactly. The compressed text overwrites the original and a readable copy is saved as <name>.original.md in a separate backup folder.

The one thing to know: the file's full text is sent to the model provider the script is set up for (the claude CLI, the Anthropic API or an OpenAI-compatible endpoint). It refuses files named like secrets, such as .env. It needs Python 3 and an explicit file path.

Good for

Claude Code users whose CLAUDE.md or notes files have grown long
Developers trying to cut the input tokens they load every session
Anyone keeping todo or preferences files in markdown or text

Install caveman-compress

Claude Code

Copy this prompt.

Install the caveman-compress skill in Claude Code. Run this command:

npx skills add https://github.com/juliusbrussee/caveman --skill caveman-compress

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Sends the file's text to the configured model provider. Trigger: /caveman-compress.

Sections in SKILL.md

Purpose
Trigger
Process
Compression Rules
Remove
Preserve EXACTLY (never modify)
Preserve Structure
Compress
Pattern
Boundaries

Key facts

Author: JuliusBrussee (repo owner)
License: Apache-2.0
Installs on skills.sh: 419,357 as of 2026-11-02
GitHub stars: 116,702 for the whole juliusbrussee/caveman repo
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
What is inside: 10 files: SKILL.md, README.md, SECURITY.md and 7 Python scripts in scripts/ (compress, detect, validate, cli, benchmark and 2 package files)
Needs: Python 3.10 or newer per the README (it runs python3 -m scripts) and a model provider: the claude CLI, the Anthropic API or an OpenAI-compatible endpoint
Last commit to the repo: 2026-11-01

What it includes

Compresses one prose file; needs an explicit path
Runs python3 -m scripts on the file. If you paste text instead of a path, it should ask for a path rather than compress inline.
Try: “/caveman-compress /Users/me/project/CLAUDE.md”
Runs code · /caveman-compress <filepath>
Checks the file type before spending any tokens
Detects whether the file is natural language. Only .md, .txt, .typ, .typst, .tex and extensionless files are compressed.
Runs code · scripts/detect.py
Calls the model to rewrite the prose
Sends the file's text to the configured provider and writes the shorter version over the original.
Runs code · scripts/compress.py
Checks the result, then fixes errors with targeted calls
Validates the output without tokens. If it finds errors it asks for targeted fixes, retries up to 2 times, then leaves the original untouched.
Runs code · scripts/validate.py
Saves <name>.original.md outside your project
The backup goes to $XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/ (or %LOCALAPPDATA% on Windows), so skill loaders do not read it as a live file.
Write · Backup file
Drops articles, filler and hedging; keeps code and paths
Never modifies .py, .js, .json, .yaml, .env and other code or config files. Mixed files get prose-only compression.
Read · Compression rules

From the official docs

Permissions

Medium risk

It sends the whole file to a model provider and replaces the original with the compressed version. Compress only files you are happy to send out, and check the backup folder after the first run.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The full file text leaves your machine
SKILL.md says the file goes to the configured model provider. Do not compress a file the provider should not see.
It overwrites the original file
The backup is saved outside the project, not beside the file. Check that it exists before you delete anything.
It runs Python scripts you did not write
The skill runs scripts in its own folder. Read scripts/compress.py first if you use it on shared or work machines.
The README flags it as Snyk High Risk
The caveman-compress README says static analysis flags subprocess and file I/O patterns, and points to SECURITY.md for why they exist. Read that file before use.

Technical details

Talks to	The model provider the script is configured for: claude CLI, Anthropic API or an OpenAI-compatible endpoint
Scopes	Runs bundled Python scripts (python3 -m scripts <file>) Overwrites the file you name and writes a backup to a data folder

Questions

What does caveman-compress do?

It rewrites a prose file, such as CLAUDE.md or a todo list, into short caveman-style text so Claude loads fewer input tokens. It keeps code, URLs, paths and commands exactly and saves a backup of the original.

How do I install caveman-compress?

Use the install box at the top of this page. Keep the whole skill folder, including scripts/, because the skill runs those Python files. The README asks for Python 3.10 or newer and says the skill is also built into the caveman plugin.

Does my file leave my machine?

Yes. SKILL.md says the full text goes to the model provider the script is configured for: the claude CLI, the Anthropic API or an OpenAI-compatible endpoint. Do not compress a file the provider should not see.

Does it overwrite my file?

Yes. The compressed version replaces the original. A readable copy is saved as <name>.original.md in a backup folder under $XDG_DATA_HOME/caveman-compress/backups/, not beside the file.

What files will it refuse or leave alone?

It refuses names that look like secrets, such as .env, credentials, secrets and .netrc, before reading them. It never modifies code or config files such as .py, .js, .json, .yaml, .toml or .sql.

Does it need an API key?

Not necessarily. The bundled README says the default path uses ANTHROPIC_API_KEY with the Anthropic SDK when that variable is set, and otherwise runs claude --print. SKILL.md also names an OpenAI-compatible endpoint as a provider option.

Is caveman-compress safe?

Review the file first, because its text is sent out and the original is replaced. It runs bundled Python scripts. On skills.sh the audits read Gen Agent Trust Hub pass, Socket pass and Snyk pass.

Can I compress text I paste into chat?

No. SKILL.md requires a file path and tells Claude to ask for one, or offer to save your text to a file first, instead of improvising an inline compression.

Information

updated Nov 2, 2026

Repository: juliusbrussee/caveman
Folder: skills/caveman-compress

juliusbrussee/caveman skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

caveman-compress SKILL.md · github.com
caveman-compress SECURITY.md · github.com
caveman-compress README · github.com
skills.sh listing and audits · skills.sh