JuliusBrussee/caveman v1.7.0

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

on GitHub

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 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.

{
  "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.

Builder has no Bash tool — can't shell out, can't push, can't delete. Refusals are terminal one-liners (too-big. split: ..., needs-confirm. op: ..., regressed. revert path:line).

🆕 New: smart multi-agent installer

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

Detects which AI coding agents are on your machine and runs each one's native install (plugin / extension / skill / rule file). Skips what you don't have. Safe to re-run.

Coverage: 33 agents. Native: Claude Code, Gemini CLI, Codex. IDE/VS Code-family: Cursor, Windsurf, Cline, Copilot, Continue, Kilo, Roo, Augment. CLI: Aider Desk, Amp, Bob, Crush, Devin, Droid, ForgeCode, Goose, iFlow, JetBrains Junie, Kiro CLI, Mistral Vibe, OpenHands, opencode, Qwen Code, Qoder, Rovo Dev, Tabnine, Trae, Warp, Replit Agent, Antigravity. Plus universal AGENTS.md / IDE rule files for everything else via npx skills.

install.sh --help for full reference.

🆕 New: caveman-init (cavepack) — drop rule files into any repo

node tools/caveman-init.js              # writes rule files for all targets
node tools/caveman-init.js --dry-run    # preview
node tools/caveman-init.js --only cline # one target only

Idempotent — uses a sentinel string to detect prior installs and skip them. Existing rule files are preserved unless --force is passed. Appendable targets (AGENTS.md, .github/copilot-instructions.md) get the caveman block appended below your existing content; replace-mode targets (.cursor/rules/caveman.mdc, .windsurf/rules/caveman.md, .clinerules/caveman.md) get fresh files. 8 tests cover: greenfield create, idempotent skip, append-vs-replace semantics, sentinel detection, --force, --dry-run, --only.

🛠 Critical fixes

• macOS installer detection was silently broken. detect_match() used awk -v RS='||' to split compound detection specs. BSD awk on macOS rejects || as a regex (illegal primary in regular expression), the awk silently failed, the fallback re-ran the whole spec as a single clause, and every compound-spec provider (cursor, windsurf, continue, kilo, roo, augment, aider-desk, bob, crush, devin, droid, forgecode, goose, iflow, kiro, mistral, openhands, opencode, qwen, rovodev, tabnine, trae, warp, replit) was undetectable on macOS. Replaced with bash parameter expansion (${rest%%||*} / ${rest#*||}) — works on bash 3.2+, no awk dependency. Verified with reproducer: compound match, fallback match, all-miss compound, single-clause all behave correctly.

• --with-mcp-shrink registered a config that 404'd on first spawn. Pre-publish, claude mcp add caveman-shrink -- npx -y caveman-shrink would store an entry that failed every time Claude tried to spawn it. Now the installer probes npm view caveman-shrink first — package missing or registry unreachable degrades to a clean manual-config skip with a print-the-snippet fallback. Default-on restored after caveman-shrink@0.1.0 shipped to npm.

• Windows install.ps1 syntax error from node -e. Powershell tokenizer truncated the embedded JS at double-quotes, breaking standalone hook install. Fix writes the script to a temp file, runs node script.js, and removes it. (Thanks @scottconverse — #250, fixes #249/#199/#72)

• /caveman argument whitelist + symlinked-parent ~/.claude support. ~/.claude symlinked to another drive (legitimate pattern) was previously refused as a "symlink attack." Now: lstat parent, resolve, verify uid match (Unix) or home-dir prefix (Windows), then allow. The flag file itself still must never be a symlink — that's the actual clobber vector. Plus argument validation: only known mode tokens reach the flag write.

• caveman-compress reliability. UTF-8 stdout enforced (Windows console no longer corrupts compressed output), empty/identical-input guards prevent silently writing zero-byte files, inline-code validation now matches the fenced-code rule, frontmatter cleanup preserves YAML.

🛡 Security

• safeWriteFlag() extended to all flag-file writes. Adds: safeWriteFlag for the active-mode flag, appendFlag (with O_APPEND) for the lifetime stats log, and readFlag (with size cap + whitelist) for the per-turn reinforcement read. The whitelist (VALID_MODES) is the load-bearing part — without it, a flag pointing at ~/.ssh/id_rsa could exfiltrate via stdout.

• Statusline scripts no longer trust the flag file blindly. Both caveman-statusline.sh and .ps1 now refuse symlinked flag/suffix files and strip control bytes (tr -d '\000-\037') so a hostile flag can't render terminal escape sequences in your status bar.

📊 Skill changes

• Ultra-mode code-symbol guard. Previously the rule "abbreviate everything" was over-aggressive — symbols like useMemo or getUserById would get truncated. Now: ultra abbreviates prose, never code/symbols/error strings.
• Auto-clarity expanded. Drop caveman for: security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread, compression itself creating ambiguity, user repeating a question.
• Typst + LaTeX added to the protected-content list — math/markup blocks pass through untouched.

📚 Docs

• README cleanup: install table now shows the smart installer first, manual install second, "What You Get" matrix collapsed to one table with footnotes, no more 4 nested <details> walls. Voice preserved (60-second readability check). Benchmark table re-anchored to real benchmarks/results/*.json runs (mean 65%, range 22-87%).
• Codex install clarified — repo-local .codex/hooks.json makes auto-activation work for this repo on macOS/Linux; for other repos, copy the hook or use $caveman manually. Codex hooks currently disabled on Windows.
• New: docs/install-windows.md — manual fallback for stubborn Windows envs (PR-merged plugin install path, symlink config for Codex).
• CLAUDE.md heavily expanded: hook system, distribution matrix, skill-system, "adding a new agent" checklist (profile slug must exist in upstream vercel-labs/skills, install.ps1 is hand-kept-in-sync with install.sh), caveman-shrink integration notes, cavecrew canonical-vs-synced layout.

🧪 Tests

• 73 tests now ship: 29 stats + 12 mcp-shrink + 8 init + 12 symlink-flag + 4 hooks (py) + 8 verify_repo + Python compress safety + inline-validate.
• All tests run on every CI push.

Upgrade

Plugin users:

claude plugin update caveman

Standalone hook users (re-run for the new statusline, MCP-shrink registration, and crash fixes):

bash hooks/install.sh --force

Curl-pipe / fresh install:

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

Other agents:

npx skills add JuliusBrussee/caveman

Don't want the MCP shrink or per-repo init? --minimal skips them. Want everything? --all.

Thanks

@scottconverse (#250 Windows fix), @ikattur-ota (#199 Windows hook reports), @confluencepoint (#72 module-loader report), and everyone who hammered the installer until the awk-on-macOS bug fell out.