I strongly prefer TypeScript with strict mode enabled for all new code. Please don't use the `any` type unless there is genuinely no way around it, and if you do, make sure to leave a comment explaining the reasoning behind it. I find that taking the time to properly type things catches a lot of bugs before they ever make it to runtime.
When you are writing React components, it would be good to use function components with hooks rather than class components. You should also try to keep each component in its own file under `src/components/`, because it really makes it a lot easier to find things later on.
You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production. Run the tests with:
```bash pnpm test --run ```
If a test is flaky, please don't just skip it. Instead, open an issue on https://github.com/acme/web-app/issues and add the `flaky` label so that we can actually track it down.
- Please use Conventional Commits for all of your commit messages.
- It would be great if you could keep pull requests small, ideally under about 400 lines of changes.
- Make sure to always update `CHANGELOG.md` whenever you change any user-facing behavior.
Strongly prefer TypeScript, strict mode on, all new code. No `any` type unless truly no way around — if used, leave comment explaining why. Proper typing catches many bugs before runtime.
React components: function components with hooks, not class components. One component per file under `src/components/` — easier to find later.
Always run test suite before pushing to main branch. Catches bugs early, prevents broken builds deploying to production. Run tests with:
```bash pnpm test --run ```
Flaky test? Don't skip. Open issue on https://github.com/acme/web-app/issues and add `flaky` label so it can be tracked down.
- Use Conventional Commits for all commit messages.
- Keep PRs small, ideally under ~400 lines changed.
- Always update `CHANGELOG.md` when changing user-facing behavior.
Real run recorded with claude-code / claude-opus-5-5. Prompt: "Compress docs/preferences.md so it costs fewer tokens when the agent loads it, but keep a backup of the original." The skill ran its bundled script (python3 -m scripts), which calls the claude CLI to do the compression. The first validation found a stray comma after a URL, and the script fixed it automatically before passing. The left and right columns are the file's exact contents before and after, unmodified, only split into headings, paragraphs and lists for display. The original was backed up to preferences.original.md in the tool's data directory.
What it does
Rewrites a natural-language file such as CLAUDE.md, project notes, a todo list or preferences in compressed prose, so it costs fewer tokens every time your agent loads it. Headings, code blocks, inline code, URLs and file paths must stay identical.
How it works
- Triggers on /caveman-compress <file> or a request to compress a memory file.
- Runs the bundled Python script, which checks the file type, size (500 KB max) and name, then sends the text to Claude. Code blocks are masked first so the model cannot change them.
- Validates the result locally. If a check fails, it asks Claude for a targeted fix, with up to 2 attempts; if it still fails, the original is left untouched.
- Writes the compressed file in place and saves the original as
<name>.original.mdin a separate data folder, so agents don't load it twice.
Good for
Large project memory files that every session loads.
Worth knowing
Only prose files (.md, .mdc, .txt, .rst, .typ, .tex and extensionless) are compressed; code and config files are skipped. Needs Python 3.10 or newer. In our trial a 1,391-byte preferences file came out at 881 bytes with every heading, code block, inline code span and URL intact.
Contains Python scripts that your agent runs. They send the content of the file you choose to Anthropic: through the Anthropic Python SDK if ANTHROPIC_API_KEY is set, otherwise through your logged-in `claude` CLI, so usage counts against your Anthropic account. They overwrite the target file and write a backup and a lock file under ~/.local/share/caveman-compress (%LOCALAPPDATA% on Windows). Files whose names look like credentials or keys are refused. We read every script and found no other network or file access. Do not compress files with content you don't want sent to Anthropic.