Skip to content

caveman-savings

What this does in one paragraph

Two small, idempotent PowerShell scripts that roll the "caveman" token-savings setup out across every house PC's Claude Code install: Apply-CavemanSavings.ps1 compresses memory files, installs a subagent-delegation rule into ~/.claude/CLAUDE.md, and caps MCP tool output; Migrate-CavemanBackups.ps1 cleans up a one-time backup-layout bug from an early version of the apply script. Neither script talks to a network or holds a secret - they only touch the local ~/.claude config directory and %LOCALAPPDATA%\caveman-compress\backups.

Scripts

scripts/Apply-CavemanSavings.ps1

Three idempotent measures, safe to re-run on any device:

  1. Compress memory files. Runs the caveman-compress skill (if the plugin is installed and Python 3.10+ is on PATH) against every .md under each project's ~/.claude/projects/*/memory directory plus the global CLAUDE.md. Originals are backed up to %LOCALAPPDATA%\caveman-compress\backups\<project>\memory\<stem>.original.md. Already-compressed files (backup exists) are skipped on re-run.
  2. Install the cavecrew delegation rule. Writes (or updates in place) a marker-fenced block in ~/.claude/CLAUDE.md telling the main agent to hand exploration, small edits, and reviews to compressed cavecrew subagents.
  3. Cap MCP tool output. Sets env.MAX_MCP_OUTPUT_TOKENS in ~/.claude/settings.json (default 10000, vs. Claude Code's built-in default of 25000). The existing file is backed up to settings.json.bak before every write.
powershell -ExecutionPolicy Bypass -File scripts\Apply-CavemanSavings.ps1
# or, with pwsh:
pwsh -File scripts/Apply-CavemanSavings.ps1 -McpOutputCap 8000 -SkipCompress

Flags: -McpOutputCap <int> (0 = skip step 3), -SkipCompress, -SkipCavecrew.

scripts/Migrate-CavemanBackups.ps1

Run this BEFORE Apply-CavemanSavings.ps1 on any device that has run an old version of the apply script. An early version of Apply-CavemanSavings.ps1 wrote compression backups to a single shared slot, backups\memory\<stem>.original.md, where same-named memory files from different projects collide - the second project's backup would be refused. The current apply script expects the per-project layout, backups\<project>\memory\<stem>.original.md, instead.

This script relocates any backups still sitting in the old shared slot:

  1. Exactly one project has a matching memory\<stem>.md -> attribute the backup there.
  2. Several candidate projects -> compare YAML frontmatter (compression preserves it verbatim); a unique frontmatter match wins.
  3. Still ambiguous -> leave the backup in the shared slot and warn. The current apply script moves such a backup aside and recompresses the file, which is harmless (compression aborts "output identical" on already-caveman text).
pwsh -File scripts/Migrate-CavemanBackups.ps1

Idempotent: an absent or empty shared backup directory means nothing to do.

Run order on an old device

1. Migrate-CavemanBackups.ps1   (clean up any old shared-slot backups first)
2. Apply-CavemanSavings.ps1     (apply/refresh the current settings)

Running them in the other order is not destructive, but the apply script will treat any backups still sitting in the old shared slot as ambiguous and leave them alone until you run the migration.

Repository layout

scripts/   Apply-CavemanSavings.ps1, Migrate-CavemanBackups.ps1
tests/     CavemanSavings.Tests.ps1, Invoke-CI.ps1  (Pester 5+, hermetic, mocked filesystem)
docs/      technical/ (architecture, security) and plain/ (plain-language README)
TESTING.md the full testing matrix (unit + coverage + churn; why Stryker is N/A here)

There is no archive/ directory yet - no file in this repo has been superseded. See "Never-delete / archive policy" below for what happens the first time one is.

Never-delete / archive policy

Superseded files are never deleted - they move to archive/ with a history-encoding filename (NAME.CURRENT-<date>.STALE-<date>.superseded-by-<reason>.ext) and a header block explaining what replaced them and why. Any secrets in an archived file would be scrubbed the same as in live files - in practice these scripts have never held a secret to begin with.

Security

  • No secrets, no network calls. Both scripts only read/write local files under ~/.claude and %LOCALAPPDATA%\caveman-compress. There is no token, API key, or bearer credential anywhere in this repo - the secret-grep CI gate and the Pester "no hardcoded secrets" test both enforce this.
  • Apply-CavemanSavings.ps1 backs up settings.json to settings.json.bak before every write, because a malformed settings.json makes Claude Code silently drop the whole file.
  • Everything the scripts do is idempotent - re-running either script is always safe.
  • See docs/technical/SECURITY.md for the full scan-results summary.