# caveman changelog

> caveman release notes.

- Vendor: caveman
- Category: AI
- Official site: https://caveman.so/
- Tracked by: What's New (https://whatsnew.fyi/product/caveman)
- Harvested from: GitHub (JuliusBrussee/caveman)
- Entries below: 10 (newest first)

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

## Releases

### v1.9.1 — v1.9.1 — 65%, honestly

- Date: 2026-07-03
- Version: v1.9.1
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.1
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.9.1

- **changed** — Headline savings is now a flat 65% everywhere, measured as average output-token reduction vs default verbose replies across a 10-prompt benchmark
- **fixed** — Session token stats in /caveman-stats are now attributed to the mode that was active when each message happened, preventing mid-session mode changes from rewriting historical session math
- **changed** — Output-reduction line in /caveman-stats is now labeled as output reduction instead of as a share of usage/quota
- **added** — New limit-headroom meter in /caveman-stats for subscription users to view session budget saved at a glance
- **added** — Documentation in docs/HONEST-NUMBERS.md explaining exactly when caveman saves tokens and when it costs them
- **fixed** — Natural-language triggers no longer misfire and one-shot modes stay one-shot
- **fixed** — mode-tracker now survives a broken stdin instead of hanging or crashing
- **fixed** — SessionStart SKILL.md path off-by-one error fixed so the ruleset injects reliably
- **added** — Hermes Agent support with symmetric install/uninstall operations verified against real Hermes installs
- **added** — Per-agent Cavecrew model overrides to pin each cavecrew subagent to the desired model
- **fixed** — spawn ENOENT is now treated as a failure instead of reporting a fake successful install
- **fixed** — No more EXDEV crash installing the Claude plugin across devices/filesystems by falling back to copy when rename cannot cross a mount
- **fixed** — JSONC settings.json reader is now string-aware and no longer mangles trailing commas inside string values
- **fixed** — install.ps1 now works when piped to iex
- **fixed** — Uninstall now matches managed hook basenames instead of a loose substring to prevent stripping the wrong entry
- **added** — Claude Code now discovers slash commands via shipped commands/*.md and caveman-stats.toml files
- **fixed** — caveman-init no longer requires a caveman checkout and runs standalone
- **fixed** — opencode --force now migrates a legacy AGENTS.md instead of wiping it
- **fixed** — OpenClaw SOUL.md data-loss issue fixed where a stray or half-present caveman marker could delete user content on next install/uninstall
- **fixed** — caveman-shrink spawn-options.js now ships in the published tarball

A maintenance + honesty release. 50 changes since `v1.9.0`, mostly hook, installer, and integration hardening, plus a full pass on how caveman states its savings number. Installs stay pinned + integrity-checked; this tag now ships `cavecrew-model-overrides.js` in the hook manifest so the `curl|bash` fallback path installs cleanly.

##### Honest numbers, one number

- **Headline savings is now a flat `65%`** everywhere (#234). We retired the `~50-65%` range and the `~75%` claim that still lived on the docs site. `65%` is the measured **average output-token reduction vs default verbose replies** across the committed 10-prompt benchmark (range 22–87%) — output tokens only. README, all plugin/extension manifests, the skill descriptions, the per-repo rule frontmatter, and the GitHub Pages site now agree.
- **`/caveman-stats` stops mislabeling savings** (#601, and the budget-% fix). Session token stats are now attributed to the mode that was active *when each message happened*, so a mid-session `/caveman ultra` no longer rewrites the whole session's math. The output-reduction line is labeled as output reduction — not as a share of your usage/quota.
- **New limit-headroom meter** in `/caveman-stats` for subscription users — session budget saved at a glance.
- **[`docs/HONEST-NUMBERS.md`](https://github.com/JuliusBrussee/caveman/blob/v1.9.1/docs/HONEST-NUMBERS.md)** documents exactly when caveman *saves* tokens and when it *costs* them (#145, #550, #506). If caveman is net-negative for your workload, that page tells you to turn it off.

##### Hooks

- **Natural-language triggers stop misfiring** and one-shot modes stay one-shot (#598, #599). `/caveman-commit` / `-review` / `-compress` no longer stick as a persistent mode.
- **`mode-tracker` survives a broken stdin** — an `error` on the stdin stream no longer hangs or crashes the hook (#538).
- **SessionStart SKILL.md path off-by-one fixed** (#587, #589) so the ruleset injects reliably.

##### Installer

- **Hermes Agent support** — install/uninstall are symmetric and verified against a real Hermes install (#524).
- **Per-agent Cavecrew model overrides** (#521) — pin each cavecrew subagent to the model you want.
- **`spawn` `ENOENT` is now treated as a failure, not a success** (#592) — a missing binary no longer reports a fake successful install.
- **No more `EXDEV` crash** installing the Claude plugin across devices/filesystems — falls back to copy when `rename` can't cross a mount (#585).
- **JSONC `settings.json` reader is string-aware** (#595) — a trailing comma inside a string value is no longer mangled during the merge.
- **`install.ps1` works when piped to `iex`** (#565), and **uninstall matches managed hook basenames** instead of a loose substring so it can't strip the wrong entry (#593).
- **Claude Code discovers the slash commands** — `commands/*.md` and `caveman-stats.toml` now ship so `/caveman`, `/caveman-stats`, etc. register (#571, #470).
- **`caveman-init` no longer needs a caveman checkout** — the per-repo rule writer runs standalone (#603).

##### Integrations

- **opencode `--force` migrates a legacy `AGENTS.md` instead of wiping it** (#594).
- **OpenClaw SOUL.md data-loss fixed** — a stray or half-present caveman marker can no longer chain into deleting user content on the next install/uninstall (#596).

##### caveman-shrink (npm MCP middleware)

- **`spawn-options.js` now ships in the published tarball** (#597) — the package was importing a file it didn't include.
- **Nested protected-segment sentinels restored** (#444) — documents with adjacent/nested protected regions round-trip through compress without losing or duplicating content.

##### /caveman-compress

- **Build files and scripts are never classified as prose** (#600) — `package.json`, `Makefile`, and shebang scripts won't get rewritten into caveman prose.

##### Repo standards & docs

- Added `SECURITY.md`, `CODE_OF_CONDUCT.md`, `.editorconfig`.
- Security/privacy docs: an explicit **no-telemetry** statem

_[Truncated at 4000 characters — full notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.1]_

### v1.9.0 — v1.9.0 — Rock pinned. Rock verified. opencode rock work now.

- Date: 2026-06-12
- Version: v1.9.0
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.9.0

- **security** — Installs now pinned and integrity-checked against the immutable v1.9.0 tag with SHA-256 verification of all hooks before execution
- **security** — Fixed reflected DOM XSS in docs site demo by building nodes with textContent instead of innerHTML
- **added** — Repo-local config via .caveman/config.json or .caveman.json to pin per-project default mode
- **added** — Natural-language brevity triggers for caveman mode including "less tokens", "be brief", and "be terse"
- **fixed** — opencode plugin now loads correctly by evaluating shared config as CommonJS by hand
- **fixed** — Real lifecycle hooks implemented for opencode including event dispatcher for session init, chat.message for mode parsing, and experimental.chat.system.transform for per-turn reinforcement
- **fixed** — Session-init flag write no longer misses one-shot opencode run sessions
- **fixed** — caveman command works through both TUI command template expansion and quoted non-interactive run path
- **fixed** — caveman-compress command file now ships
- **fixed** — Copilot detection via extension directories
- **fixed** — npx skills add honors the agent profile
- **fixed** — Orphaned managed hooks pruned from settings.json
- **fixed** — No double hook-wiring when plugin manifest already wires them
- **fixed** — MCP-shrink is opt-in and requires an upstream
- **fixed** — opencode config directory corrected to ~/.config/opencode on Windows
- **fixed** — PowerShell $Args collision resolved
- **fixed** — cavecrew agent copies strip tools: prefix for opencode
- **fixed** — caveman-compress UTF-8 pinned subprocess to fix Windows cp1252 crash
- **fixed** — caveman-compress claude.cmd resolution on Windows
- **fixed** — caveman-compress YAML frontmatter preserved

##### Security

- **Installs now pinned + integrity-checked** (#261, #262)
  `curl|bash` and detached installs no longer fetch hook files from the moving
  `main` branch — they download from the immutable `v1.9.0` tag and verify
  every hook against `src/hooks/checksums.sha256` (SHA-256) before anything
  executes. Mismatch aborts the install. This is the first tag shipping the
  manifest, so enforcement is fully active as of this release.

- **`fix(docs)`: escape user input in the demo terminal** (#438)
  The docs site demo interpolated user input via `innerHTML` — a real
  reflected DOM XSS. Nodes are built with `textContent` now.

##### opencode actually works now

Smoke-tested against a real opencode runtime for the first time — and the
plugin turned out to never load: opencode runs plugins inside a compiled Bun
binary where both `require()` of on-disk files and `await import()` of CJS
silently fail. Fixed by evaluating the shared config as CommonJS by hand.
Also fixed in the same pass, all verified end-to-end against opencode 1.4.0:

- Real lifecycle hooks: `event` dispatcher for session init, `chat.message`
  for mode parsing, `experimental.chat.system.transform` for per-turn
  reinforcement — the old hook keys never existed and were silently ignored (#418, #421)
- Session-init flag write no longer misses one-shot `opencode run` sessions
- `/caveman <level>` works both through the TUI command template expansion
  and the quoted non-interactive `run` path
- `/caveman-compress` command file now ships (was gitignored) (#398, #426, #451, #464)

##### Features

- **Repo-local config** (#429) — check in `.caveman/config.json` (or
  `.caveman.json`) to pin a per-project default mode for the whole team.
  Resolution order: env var → repo config → user config → `full`.
- **Natural-language brevity triggers** (#248) — "less tokens", "be brief",
  "be terse" now activate caveman mode.

##### Fixes

- **Installer**: Copilot detection via extension dirs (#437), `npx skills add`
  honors the agent profile again (#395), orphaned managed hooks pruned from
  `settings.json` (#472), no double hook-wiring when the plugin manifest
  already wires them (#393), MCP-shrink is opt-in and requires an upstream
  (#380), opencode config dir corrected to `~/.config/opencode` on Windows
  (#376), PowerShell `$Args` collision (#414), cavecrew agent copies strip
  `tools:` for opencode (#443)
- **caveman-compress**: UTF-8 pinned subprocess (fixes Windows cp1252 crash,
  #388/#152), `claude.cmd` resolution on Windows (#435), YAML frontmatter
  preserved (#424), backups written outside the source tree (#420)
- **Skill**: replies preserve the user's language (#446), no self-reference
  (#469), full-mode output guardrails (#322), fixed corrupted wenyan example
- **Stats**: Opus 4.5+ output price corrected $75 → $25/M (#466), statusline
  pickaxe renders on Windows (#459)
- **MCP-shrink**: `npx`/`.cmd` upstream resolution on Windows (#387)

##### Maintenance

- Sponsors section (welcome, Atlas Cloud), caveman-code + cavegemma in the
  ecosystem table, stale pre-cleanup dotdir mirrors removed, init tests no
  longer touch the developer's real `~/.openclaw` workspace.

##### Upgrade

```
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
```

Existing installs: re-run the same one-liner — idempotent. opencode users
should re-run with `--force` to pick up the fixed plugin:
`npx -y github:JuliusBrussee/caveman -- --only opencode --force`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

### v1.8.2 — v1.8.2 — installer bug fixes

- Date: 2026-05-12
- Version: v1.8.2
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.2
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.8.2

- **fixed** — curl|bash one-liner now installs skills by passing --yes --all to both the per-provider call and the auto-detect fallback
- **fixed** — strip stray YAML fences from commands/caveman-init.toml so Gemini CLI extension loads cleanly
- **fixed** — rename codex_hooks to hooks in .codex/config.toml to use the canonical key

##### Fixes

- **`fix(install)`: curl|bash one-liner now actually installs skills** (#370)
  Upstream `skills` CLI rendered its interactive skill-picker TUI under
  `curl|bash` (stdin not a TTY), got no selection, exited 0, and installed
  nothing — while our installer cheerfully reported `done`. Now passes
  `--yes --all` to both the per-provider call and the auto-detect fallback
  so every detected agent gets all 7 caveman skills, no prompt required.

- **`fix(gemini)`: strip stray YAML fences from `commands/caveman-init.toml`** (#372, dup #326)
  Gemini CLI's `FileCommandLoader` rejected the file with `Failed to parse TOML`
  on extension install. Fences gone — extension loads cleanly.

- **`fix(codex)`: rename `codex_hooks` → `hooks` in `.codex/config.toml`** (#350)
  Codex source confirms `hooks` is the canonical key; `codex_hooks` is a legacy
  alias that emits a deprecation log on every session.

##### Upgrade

```
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
```

Existing installs: re-run the same one-liner — idempotent, picks up the new flags.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

### v1.8.1 — v1.8.1 — Hotfix: curl|bash one-liner

- Date: 2026-05-10
- Version: v1.8.1
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.1
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.8.1

- **fixed** — install.sh defaults BASH_SOURCE[0] to empty to prevent unbound variable error under curl|bash with set -u
- **fixed** — install.sh and install.ps1 no longer pass -- between npx and the package to avoid unknown flag rejection
- **fixed** — bin/install.js parseArgs now accepts a bare -- as a no-op POSIX end-of-options marker
- **added** — New regression test asserts -- is accepted

##### Hotfix for v1.8.0 — curl|bash one-liner

The headline install command in v1.8.0 was broken at first contact:

```
$ curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only openclaw
bash: line 39: BASH_SOURCE[0]: unbound variable
error: unknown flag: --
```

Two regressions — neither caught by CI because both are stdin-pipe-only.

###### What broke

1. **`set -u` + `${BASH_SOURCE[0]}` is fatal under curl|bash.** When bash reads from stdin, `BASH_SOURCE` is unset; the strict-mode shell trapped on the first reference.
2. **`--` separator survived `npx`.** `install.sh` and `install.ps1` passed `npx -y "github:..." -- "$@"` and modern npx forwards the literal `--` to the package, which `parseArgs` rejected as `unknown flag: --`.

###### What this release fixes

- `install.sh` defaults `BASH_SOURCE[0]` to empty so the curl-pipe path falls through cleanly under `set -u`.
- `install.sh` + `install.ps1` no longer pass `--` between npx and the package — npm 7+ npx forwards trailing args correctly without it.
- `bin/install.js` `parseArgs` now accepts a bare `--` as a no-op (POSIX end-of-options marker). Future shim drift can't re-break this.
- New regression test asserts `--` is accepted.

###### Upgrade

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only openclaw
```

If you tried v1.8.0 and got the error above, just re-run this command. No state was written on the failed install.

###### What's unchanged from v1.8.0

Everything else — OpenClaw, opencode, the installer fixes, the test bump (now 51 tests). See [v1.8.0 release notes](https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.0) for the full feature list.

### v1.8.0 — v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.

- Date: 2026-05-10
- Version: v1.8.0
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.0
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.8.0

- **added** — Add OpenClaw (lobster) as a first-class always-on agent target via skill drop at ~/.openclaw/workspace/skills/caveman/SKILL.md and SOUL.md marker-fenced bootstrap block
- **added** — Add opencode native plugin as always-on replacement for npx-skills fallback, with session.created and tui.prompt.append lifecycle hooks
- **added** — Add six opencode slash-command prompt templates (/caveman, /caveman-commit, /caveman-review, /caveman-compress, /caveman-stats, /caveman-help)
- **added** — Add three cavecrew subagents for opencode plugin
- **added** — Add seven skill folders for opencode (caveman, caveman-commit, caveman-review, caveman-help, caveman-stats, caveman-compress, cavecrew)
- **added** — Add Tier-3 always-on ruleset in opencode AGENTS.md fenced with <!-- caveman-begin --> / <!-- caveman-end --> markers
- **added** — Add caveman-shrink MCP server to opencode.json (enabled by default via --with-mcp-shrink)
- **added** — Add seven new tests covering --only typo validation, --config-dir ~ expansion, --help scope disclosure, malformed-input safety, AGENTS.md fence assertion, plugin.js hand-edit survival, and fenced uninstall preservation
- **changed** — Consolidate repository layout by moving hooks/, rules/, tools/, mcp-servers/ under src/
- **changed** — Change opencode plugin payload to no longer overwrite on reinstall, requiring --force flag to update user edits
- **changed** — Change opencode AGENTS.md to use fence markers for uninstall, preserving legacy un-fenced blocks by default unless --force is passed
- **changed** — Update --config-dir help text to disclose that it does not sandbox claude plugin install, gemini extensions install, opencode (XDG_CONFIG_HOME), or openclaw (OPENCLAW_WORKSPACE)
- **fixed** — Fix downloadTo Promise that was unawaited on https fallback path, causing silent partial install when curl was missing
- **fixed** — Fix --only <typo> to validate against provider matrix and exit with code 2 instead of silently exiting 0
- **fixed** — Fix .bak files being silently overwritten on every reinstall by preserving them on first install only
- **fixed** — Fix opencode plugin payload (plugin.js, package.json, caveman-config.cjs) being rewritten on every reinstall by honoring --force flag
- **fixed** — Fix uninstall to probe claude plugin list and gemini extensions list before firing uninstaller to eliminate stderr noise on cold uninstalls
- **fixed** — Fix uninstall to also run claude mcp remove caveman-shrink when the subcommand exists
- **fixed** — Fix removeCavemanHooks to no longer crash on malformed pre-existing settings.hooks
- **fixed** — Fix --config-dir value to be ~-expanded

> ⚠️ **v1.8.0's curl|bash one-liner was broken** (BASH_SOURCE unbound + stray `--` to parseArgs). Use [v1.8.1](https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.1) instead — same release contents plus the hotfix.

##### Brain still big. Two more mouths now small.

This release teaches caveman to two new agents: **OpenClaw** (the lobster) and **opencode** (the TUI). Both now grunt fluent caveman from message one — no `/caveman` per session, no setup nag.

Plus a stack of installer fixes from a top-to-bottom review of `bin/install.js`.

##### What's new

###### 🦞 OpenClaw — first-class always-on target

`npx -y github:JuliusBrussee/caveman -- --only openclaw` and the lobster talks like a caveman every turn.

Two tiny writes do the work:
- **Skill drop** at `~/.openclaw/workspace/skills/caveman/SKILL.md` — spec-correct frontmatter (`version`, `always: true`), discoverable by `openclaw skills list`.
- **SOUL.md nudge** — marker-fenced bootstrap block at `~/.openclaw/workspace/SOUL.md`, auto-injected each turn under "Project Context". Stays well under OpenClaw's 12K-per-file cap.

Idempotent on both writes. Uninstall strips the skill folder + the marker block, leaves your other workspace content alone. Custom workspace via `OPENCLAW_WORKSPACE`.

See README's *Lobster, Meet Rock* section for the longer pitch.

###### 🤖 opencode — native plugin replaces npx-skills fallback

opencode goes from "manual `/caveman` per session" to **always-on**. The installer drops:

- A real opencode plugin (`~/.config/opencode/plugins/caveman/`) using `session.created` and `tui.prompt.append` lifecycle hooks
- Six slash-command prompt templates (`/caveman`, `/caveman-{commit,review,compress,stats,help}`)
- Three cavecrew subagents
- Seven skill folders (caveman, caveman-commit/review/help/stats/compress, cavecrew)
- A Tier-3 always-on ruleset in `AGENTS.md`, **fenced** with `<!-- caveman-begin -->` / `<!-- caveman-end -->` markers (clean uninstall later)

`opencode.json` gets patched with the plugin entry plus the `caveman-shrink` MCP server (when `--with-mcp-shrink` is on, which is the default).

opencode reaches Tier-1 minus the statusline (opencode's TUI exposes no plugin-writable badge).

###### 🛠️ Installer rewrite + correctness fixes

The unified `bin/install.js` got reviewed end-to-end. What changed in this release:

**Bug fixes (high-severity)**
- `downloadTo` Promise was unawaited on the https fallback path — silent partial install if `curl` was missing. Now properly awaited.
- `--only <typo>` used to exit `0` with no work done. Now validates against the provider matrix and exits `2` with `error: unknown agent: <id>`.
- `.bak` files were silently overwritten on every reinstall, destroying recovery. Now preserved on first install only.
- opencode plugin payload (`plugin.js`, `package.json`, `caveman-config.cjs`) used to be rewritten on every reinstall, wiping user edits. Now honors the same `!--force` skip the rest of the payload uses.
- `--config-dir` help text now discloses scope honestly: it does **not** sandbox `claude plugin install`, `gemini extensions install`, opencode (`XDG_CONFIG_HOME`), or openclaw (`OPENCLAW_WORKSPACE`).

**Idempotency / hygiene**
- Uninstall now probes `claude plugin list` / `gemini extensions list` before firing the uninstaller — no more "Plugin not installed" stderr noise on cold uninstalls.
- Uninstall now also runs `claude mcp remove caveman-shrink` (when the subcommand exists).
- opencode AGENTS.md is now fenced with `<!-- caveman-begin -->` / `<!-- caveman-end -->`. Uninstall strips just the fenced block, preserving any user content above and below it.
- `--config-dir` value is now `~`-expanded.
- `removeCavemanHooks` no longer crashes on malformed pre-existing `settings.hooks` (e.g. when a user hand-edited and broke things).

###### 🧹 Repo layout consolidated

`hooks/`, `rules/`, `tools/`, `mcp-servers/` all moved under `src/`. Sources of truth are at the top of the tree; distribution mirrors li

_[Truncated at 4000 characters — full notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.0]_

### v1.7.0 — v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink

- Date: 2026-05-01
- Version: v1.7.0
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.7.0
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.7.0

- **added** — Add /caveman-stats command to display real token receipts including output tokens, cache-read tokens, estimated tokens saved, and cost savings with support for lifetime aggregation via --all and time windows via --since
- **added** — Add statusline savings badge showing lifetime tokens saved, enabled by default and configurable via CAVEMAN_STATUSLINE_SAVINGS environment variable
- **added** — Publish caveman-shrink as npm package, an MCP middleware that compresses description fields in tools/list, prompts/list, and resources/list responses while preserving code, URLs, paths, and identifiers
- **added** — Add cavecrew, three caveman-mode subagents for Claude Code that emit approximately 60% fewer handoff tokens than vanilla agents: cavecrew-investigator for read-only code location queries, cavecrew-builder for surgical 1-2 file edits, and cavecrew-reviewer for diff and file review
- **added** — Add smart multi-agent installer that detects 33 AI coding agents on the machine and runs each one's native installation with flags for --minimal, --with-hooks, --with-mcp-shrink, --with-init, --list, --only, and --dry-run options
- **added** — Add caveman-init tool to drop rule files for supported agents into any repository
- **fixed** — Fix critical macOS installer bug that was silently breaking detection for all compound-spec providers including Cursor, Windsurf, Continue, and 28 others

##### v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink

The biggest release since v1.0. Caveman now has measurement (real token receipts, not vibes), an installer that detects 30+ agents and runs each one's native install, three caveman-mode subagents that emit ~60% fewer handoff tokens than vanilla, an MCP middleware that shrinks tool descriptions in flight, and a one-command rule-file dropper for any repo.

Plus a critical macOS installer fix that was silently breaking detection for **every compound-spec provider** (cursor / windsurf / continue / 28 others).

---

###### 🆕 New: `/caveman-stats` — real receipts, not vibes

```
Caveman Stats
──────────────────────────────────
Session:  ...projects/my-app/abc123.jsonl
Turns:    47
──────────────────────────────────
Output tokens:         3,210
Cache-read tokens:     128,400
──────────────────────────────────
Est. tokens saved:     5,961 (~65%)
Est. saved (USD):      ~$0.089
──────────────────────────────────
Memory compressed:     2 files, ~1,920 tokens saved per session start
```

Reads the active Claude Code session JSONL directly — no model-side guessing. Pricing matches by model-id prefix (`claude-sonnet-4-*` → $15/M, etc.) so it stays correct across point releases. Lifetime aggregation via `--all`, time window via `--since 7d` / `--since 24h`, tweetable one-liner via `--share`.

**Statusline savings badge** — on by default. After your first `/caveman-stats` run the bar shows `[CAVEMAN] ⛏ 12.4k` (lifetime tokens saved) and updates every run. Opt out with `CAVEMAN_STATUSLINE_SAVINGS=0`. Suffix file is absent until stats has run, so fresh installs render no fake number.

29 tests cover: pricing prefix-match, lifetime aggregation latest-per-session semantics, `--since` parsing, malformed-duration rejection, compressed-memory pair detection, statusline default-on / opt-out / fresh-install behaviors, ANSI-escape stripping in the suffix file, and symlink-safe history append.

###### 🆕 New: `caveman-shrink` — MCP middleware (published to npm)

[`caveman-shrink@0.1.0`](https://www.npmjs.com/package/caveman-shrink) is a stdio proxy that wraps any MCP server, intercepts `tools/list` / `prompts/list` / `resources/list` responses, and compresses the `description` fields. Same boundaries as the parent skill — code, URLs, paths, and identifiers stay byte-for-byte identical.

```jsonc
{
  "mcpServers": {
    "fs-shrunk": {
      "command": "npx",
      "args": ["caveman-shrink", "npx", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}
```

V1 deliberately does **not** touch tool-call response bodies or request payloads — only prose-y description fields. Configurable extra fields via `CAVEMAN_SHRINK_FIELDS`, debug deltas via `CAVEMAN_SHRINK_DEBUG=1`. Auto-registered by `install.sh` (use `--minimal` to skip). 12 tests cover: article/filler/hedge stripping, fenced code preservation, inline code preservation, URL preservation, filesystem-path preservation, identifier preservation, real MCP-style descriptions, nested-object walking.

###### 🆕 New: `cavecrew` — three caveman subagents for Claude Code

Subagent tool-output gets injected back into the main thread context. Vanilla `Explore` / reviewer agents return verbose prose that eats main-context fast. Cavecrew agents emit caveman-ultra by default, ~60% fewer handoff tokens.

| Subagent | Model | Job | Output |
|---|---|---|---|
| `cavecrew-investigator` | haiku | Read-only locator. "Where is X defined?" / "what calls Y?" / "map this dir" | `path:line — \`symbol\` — note`, grouped headers when 3+ |
| `cavecrew-builder` | sonnet | 1-2 file surgical edits. Refuses 3+ file scope. | `path:line-range — change ≤10 words.` + `verified: re-read OK` |
| `cavecrew-reviewer` | haiku | Diff/branch/file review. One line per finding. | `path:line: 🔴 bug: problem. fix.` + severity totals |

Builder has no `Bash` tool — can't shell out, can't push, can't delete. Refusals are terminal one-liners (`too-big. split: ...`, `

_[Truncated at 4000 characters — full notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.7.0]_

### v1.6.0 — v1.6.0 — Hardening release: hook crash fixes + symlink-safe flag writes

- Date: 2026-04-15
- Version: v1.6.0
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.6.0
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.6.0

- **fixed** — Hooks no longer crash when an ancestor package.json declares "type": "module" by shipping hooks/package.json with {"type": "commonjs"}
- **fixed** — ${CLAUDE_PLUGIN_ROOT} is now quoted in plugin.json to fix plugin install paths containing spaces
- **fixed** — Codex hook config shape updated to the current spec with matcher + nested hooks array
- **security** — safeWriteFlag() helper hardens all flag file writes against symlink attacks by refusing symlink parent directories, refusing symlink targets, opening with O_NOFOLLOW where supported, writing atomically via temp file + rename(), and setting 0600 permissions on creation
- **changed** — CLAUDE_CONFIG_DIR env var is now respected across all hooks, statusline scripts, and install/uninstall scripts
- **changed** — Natural-language activation now matches "talk like caveman", "caveman mode", "stop caveman", and "normal mode" phrases in addition to /caveman slash commands
- **added** — Per-turn caveman reinforcement via hookSpecificOutput reminder on every UserPromptSubmit to maintain caveman style across context drift
- **fixed** — skills/compress/scripts/ is now real Python files instead of broken Git symlinks on Windows and non-symlink-following platforms
- **fixed** — README link fixes for several broken anchors
- **changed** — Consolidated all flag file writes through safeWriteFlag() helper

##### v1.6.0 — Hardening release

11 community PRs merged plus a hardened security model for the flag file. This release fixes two real crash bugs that were silently breaking installs, two local-file-clobber vulnerabilities, and several portability gaps.

###### Critical fixes

- **Hooks no longer crash when an ancestor `package.json` declares `"type": "module"`.** Before this fix, any user with `~/.claude/package.json` set to ESM (common with several Claude Code plugins) hit `ReferenceError: require is not defined in ES module scope` on every session. SessionStart and UserPromptSubmit hooks both silently failed, the flag file was never written, and the statusline badge disappeared. Fixed by shipping `hooks/package.json` with `{"type": "commonjs"}` so the hooks pin themselves to CJS regardless of ancestor settings. (Thanks @malakhov-dmitrii — #174)

- **`${CLAUDE_PLUGIN_ROOT}` is now quoted in `plugin.json`.** Plugin install paths containing spaces (e.g. `~/Library/Application Support/...` on macOS, `C:\Users\Some Name\...` on Windows) used to break the `node` invocation entirely. (Thanks @MukundaKatta — #171)

- **Codex hook config shape updated to the current spec.** The old shape silently no-op'd on Codex with hooks enabled. New shape uses the `matcher` + nested `hooks` array. Repo also now ships `.codex/config.toml` with `codex_hooks = true` so auto-activation actually works inside this repo on macOS/Linux. (Thanks @davidbits — #148)

###### Security fixes

- **`safeWriteFlag()` helper hardens all flag file writes against symlink attacks.** The flag file at `~/.claude/.caveman-active` is at a predictable path. Before this fix, a local attacker (or any sibling process running as the same user but with a smaller blast radius — sandboxed extension, container with a `~/.claude` bind mount, etc.) could replace the flag with a symlink to any user-writable file (`~/.ssh/authorized_keys`, `~/.bashrc`) and the next hook write would clobber the symlink target. The new helper, defined once in `hooks/caveman-config.js` and used by every write site:

  - Refuses if the flag's parent directory is itself a symlink
  - Refuses if the existing flag target is a symlink
  - Opens with `O_NOFOLLOW` where supported (Linux/macOS)
  - Writes atomically via temp file + `rename()`
  - Sets `0600` permissions on creation

  Verified against a real symlink-redirect attack: the target file is left untouched. (Thanks @tuanaiseo — #70 + #71, consolidated into one shared helper)

###### Quality of life

- **`CLAUDE_CONFIG_DIR` env var is now respected across all hooks**, statusline scripts, and install/uninstall scripts. Users with non-default Claude Code config locations no longer have to symlink things into `~/.claude/`. (Thanks @BrendanIzu — #146)

- **Natural-language activation actually works now.** The README has long claimed `talk like caveman` and `caveman mode` activate caveman, and `stop caveman` / `normal mode` deactivate it. The mode tracker hook only ever matched `/caveman` slash commands, so the natural-language phrasings were a lie. Now they're not. (Thanks @hummat — #120)

- **Per-turn caveman reinforcement.** SessionStart injects the full ruleset once, but other plugins inject competing style instructions every turn. The mode tracker now emits a small `hookSpecificOutput` reminder on every UserPromptSubmit so the model keeps caveman style even after context drift. Skipped for independent modes (`commit`, `review`, `compress`) which have their own behavior. (Thanks @hummat — #119)

- **`skills/compress/scripts/` is now real Python files instead of broken Git symlinks.** Previously symlinks inside the skills directory broke on Windows and on platforms that don't follow them. The compress sub-skill now ships as proper modules: `compress.py`, `detect.py`, `validate.py`, `benchmark.py`, plus `cli.py` and `__main__.py`. (Thanks @gladkia — #153)

- **README link fixes** — several broken anchors corrected. (Thanks @nervana21 — #169)

###### Int

_[Truncated at 4000 characters — full notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.6.0]_

### v1.5.1

- Date: 2026-04-11
- Version: v1.5.1
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.5.1
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.5.1

- **changed** — Activation hook now reads skills/caveman/SKILL.md at runtime instead of hardcoding rules inline
- **changed** — Plugin installs resolve SKILL.md relative to the plugin root
- **added** — Standalone installs fall back to a built-in minimal ruleset when no skills directory is present
- **changed** — commit/review/compress modes skip SKILL.md machinery entirely and use their own independent skill files
- **changed** — Consolidate install details for Cursor, Windsurf, Cline, and Copilot into one block
- **fixed** — Fix bash statusline badge example to use ANSI-C quoting so escape sequences render correctly
- **fixed** — Fix /caveman with off default writing "off" to flag file by guarding against off and deleting the flag file

##### Runtime SKILL.md loading

Activation hook now reads `skills/caveman/SKILL.md` at runtime instead of hardcoding rules inline. Edits to the source of truth propagate automatically — no duplication to go stale.

- Plugin installs resolve SKILL.md relative to the plugin root
- Standalone installs (hooks only, no skills dir) fall back to a built-in minimal ruleset
- `commit`/`review`/`compress` modes skip SKILL.md machinery entirely — they have their own independent skill files

##### Docs

- **Consolidate install details** — Cursor, Windsurf, Cline, and Copilot install instructions merged into one block (#106)
- **Fix bash statusline badge example** — use ANSI-C quoting so escape sequences render correctly (#57)

##### Bug fixes

- **Fix `/caveman` with `off` default writing "off" to flag file** — mode tracker now guards against `off` and deletes the flag file, matching the activate hook behavior

### v1.5.0

- Date: 2026-04-11
- Version: v1.5.0
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.5.0
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.5.0

- **added** — Make default mode configurable via CAVEMAN_DEFAULT_MODE environment variable or config file at ~/.config/caveman/config.json, with fallback to 'full'
- **added** — Add 'off' mode to skip session-start activation entirely
- **added** — Add /caveman-help command to display a quick-reference card covering all modes, skills, triggers, configuration, and deactivation
- **changed** — Update all install/uninstall scripts (bash and PowerShell) to support configurable default mode
- **fixed** — Fix /caveman with 'off' default writing 'off' to flag file by guarding against 'off' mode and deleting flag file
- **fixed** — Fix swapped step comments in uninstall.sh where steps 3 and 4 were numbered out of order
- **fixed** — Update CLAUDE.md documentation to reference configurable default mode instead of hardcoded 'full' default

##### Configurable default mode

Default mode is now configurable instead of always starting at `full`. Resolution order:

1. `CAVEMAN_DEFAULT_MODE` environment variable (highest priority)
2. Config file at `~/.config/caveman/config.json` (XDG-compliant, cross-platform)
3. `'full'` (unchanged default — fully backward compatible)

```bash
export CAVEMAN_DEFAULT_MODE=ultra
```

```json
{ "defaultMode": "lite" }
```

All install/uninstall scripts (bash + PowerShell) updated. Invalid modes silently fall through to default.

Closes #86

##### "off" mode — disable auto-activation

Set `CAVEMAN_DEFAULT_MODE=off` or `{"defaultMode": "off"}` in config to skip session-start activation entirely. No flag file written, no rules injected. User can still manually activate with `/caveman` during the session.

##### `/caveman-help` quick-reference card

New skill — type `/caveman-help` to display a terse reference card covering all modes, skills, triggers, configuration, and deactivation. One-shot display, no mode change.

Works in: Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Copilot, and all agents via `npx skills`.

##### Bug fixes

- **Fix `/caveman` with `off` default writing "off" to flag file** — mode tracker now guards against `off` and deletes the flag file, matching the activate hook behavior
- **Add test coverage for `off` mode** — both activate hook and mode tracker paths now tested
- **Fix swapped step comments in `uninstall.sh`** — steps 3 and 4 were numbered out of order
- **Update stale CLAUDE.md** — `/caveman` default now references configurable default instead of hardcoded `full`

### v1.4.1

- Date: 2026-04-11
- Version: v1.4.1
- Original notes: https://github.com/JuliusBrussee/caveman/releases/tag/v1.4.1
- Permalink: https://whatsnew.fyi/product/caveman/releases/v1.4.1

- **fixed** — Fix Codex plugin compress skill on Windows by replacing symlinks with real file copies and adding CI sync step for future propagation
- **added** — Add configurable default caveman mode via CAVEMAN_DEFAULT_MODE environment variable or ~/.config/caveman/config.json with fallback to 'full'
- **added** — Add /caveman-help skill to display a quick-reference card covering all modes, skills, triggers, configuration, and deactivation

##### Fix: Codex plugin compress skill broken on Windows

The `compress` skill in the Codex plugin shipped as symlinks (`plugins/caveman/skills/compress/SKILL.md` and `scripts`). On Windows and any git setup with `core.symlinks=false`, these checked out as plain text files containing the target path — causing Codex to reject the skill with "missing YAML frontmatter."

###### Changes
- Replaced symlinks with real file copies (scripts identical to source, SKILL.md adapted for plugin context)
- Added CI sync step so future edits to `caveman-compress/` auto-propagate to the plugin copy

Closes #92

---

##### Feature: Configurable default caveman mode

Default mode is now configurable instead of always starting at `full`. Resolution order:

1. `CAVEMAN_DEFAULT_MODE` environment variable (highest priority)
2. Config file at `~/.config/caveman/config.json` (XDG-compliant, cross-platform)
3. `'full'` (unchanged default — fully backward compatible)

**Example — env var:**
```bash
export CAVEMAN_DEFAULT_MODE=ultra
```

**Example — config file:**
```json
{ "defaultMode": "lite" }
```

All install/uninstall scripts (bash + PowerShell) updated. Invalid modes silently fall through to default.

Closes #86

---

##### Feature: `/caveman-help` quick-reference card

New skill — type `/caveman-help` to display a terse reference card covering all modes, skills, triggers, configuration, and deactivation. One-shot display, no mode change.

Works in: Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Copilot, and all agents via `npx skills`.