caveman releases

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

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 for the full feature list.

⚠️ v1.8.0's curl|bash one-liner was broken (BASH_SOURCE unbound + stray -- to parseArgs). Use 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 live below. See CLAUDE.md for the new map.

Tests

50/50 passing (npm test). Up from 43 in v1.7.0 — seven new tests cover:

• --only typo validation
• --config-dir ~ expansion
• --help discloses --config-dir scope
• removeCavemanHooks malformed-input safety
• AGENTS.md fence assertion
• opencode plugin.js hand-edit survives reinstall (without --force)
• AGENTS.md fenced uninstall preserves user prefix and suffix

Verify after upgrade

node bin/install.js --list      # 34 providers; OpenClaw + opencode visible
node bin/install.js --help      # --config-dir scope is now spelled out

For the lobster: npx -y github:JuliusBrussee/caveman -- --only openclaw.

For opencode: npx -y github:JuliusBrussee/caveman -- --only opencode (needs a local clone or npx-extracted repo for the native plugin payload).

Upgrade

Existing users:

npx -y github:JuliusBrussee/caveman

Auto-detects everything you already had + picks up OpenClaw and opencode if present. Safe to re-run.

Behavior changes worth knowing

• opencode plugin payload no longer overwrites on reinstall. If you've edited ~/.config/opencode/plugins/caveman/plugin.js and want the new version, pass --force. Without --force, your edits stay.
• opencode AGENTS.md from v1.7.x and earlier was un-fenced. Reinstall won't replace a legacy block by default; pass --force to rewrite with the fenced version. Uninstall still removes legacy blocks correctly.

Caveman ecosystem

• caveman (you here) — output compression
• cavemem — cross-agent memory
• cavekit — spec-driven build loop

One rock. Two rock. Three rock. That it.

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)

[email protected] 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.

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

| Flag | What |
|---|---|
| --all | Plugin + hooks + statusline + MCP shrink + per-repo rule files. The full ride. |
| --minimal | Plugin/extension only. |
| --with-hooks | Standalone hooks + statusline + stats badge. On by default. |
| --with-mcp-shrink | Register caveman-shrink MCP proxy. On by default. |
| --with-init | Drop per-repo rule files for Cursor/Windsurf/Cline/Copilot/AGENTS.md. |
| --list | Print full agent matrix and exit. |
| --only <agent> | One target only (repeatable). |
| --dry-run | Preview, write nothing. |

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 [email protected] 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.

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)

export CAVEMAN_DEFAULT_MODE=ultra

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

Highlights

• Add Claude Code statusline badge support, including shell and PowerShell badge scripts.
• Add standalone Claude hook install/uninstall flows for macOS/Linux and Windows, with safer settings merge behavior and better reinstall checks.
• Add always-on rule/instruction files plus sync workflow for Cursor, Windsurf, Cline, Copilot, Codex, Gemini, and repo agent docs.
• Add local verification coverage for hook install/uninstall flows, synced artifacts, manifests, syntax, and caveman-compress fixtures.
• Improve caveman-compress validation and wrapper stripping, plus benchmark/token-count handling updates.
• Expand docs across README, hooks docs, and repo guidance, including clearer install behavior and statusline setup expectations.

Full Changelog: https://github.com/JuliusBrussee/caveman/compare/v1.3.5...v1.4.0

What's new

• Plugin-bundled hooks — SessionStart and UserPromptSubmit hooks now ship in plugin.json. Install as a plugin and they auto-activate — no install.sh needed.
• Mode-aware statusline badge — flag file at ~/.claude/.caveman-active now stores the active mode (full, lite, ultra, wenyan, commit, review). Statusline scripts can show [CAVEMAN:ULTRA] etc.
• UserPromptSubmit mode tracker — detects /caveman ultra, /caveman-commit, etc. and updates the flag file in real time.
• Best practices alignment — hooks use explicit timeout: 5, statusMessage, and follow official Claude Code hook docs.
• Cleaner README — install section restructured: plugin install (recommended, includes hooks) vs npx skills (skills only).

Install

claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

Or for any agent: npx skills add JuliusBrussee/caveman

What's new

• Intensity levels — choose lite, full (default), or ultra caveman compression. Fine-grained control over how aggressive the token savings are.
• Auto-Clarity — caveman mode automatically drops compression for security warnings and destructive operations. Safety-critical output stays crystal clear.
• caveman-compress skill — new standalone skill that compresses natural language memory files (CLAUDE.md, todos, preferences) into caveman format. Preserves all technical substance while cutting tokens.
• GitHub Action for SKILL.md sync — auto-syncs SKILL.md copies on push to main, keeping all skill entry points consistent.
• GitHub Pages landing site — project now has a proper landing page.
• SKILL.md prompt compression — ~40% fewer tokens in the skill prompt while keeping all behavioral anchors.

Upgrade

Update your skill installation to get intensity levels and auto-clarity automatically.

Full Changelog: https://github.com/JuliusBrussee/caveman/compare/v1.1.0...v1.2.0

What new

• Reproducible benchmark system — benchmarks/run.py call Claude API, measure real output token counts normal vs caveman, auto-update README table. No more fake numbers.
• Real benchmark data — 10 coding prompts, actual API measurements. Average 65% token savings (range 22%–87%).
• Codex plugin support — caveman now work in OpenAI Codex too.
• Contributing guide + issue templates for bug reports and feature requests.

Run benchmarks yourself

cd benchmarks
pip install -r requirements.txt
python run.py --dry-run          # preview, no API calls
python run.py --update-readme    # run + update README table

Full Changelog: https://github.com/JuliusBrussee/caveman/compare/v1.0.0...v1.1.0

🪨 v1.0.0 — why use many token when few token do trick

First release. Caveman here. Save token. Save money. Brain still big.

What caveman do

Make Claude talk like smart caveman. Cut ~75% tokens. Keep all technical substance. Code stay normal. Only English get caveman treatment.

Feature

• ~75% less token — less cost, fast response, same accuracy
• One rock install — npx skills add JuliusBrussee/caveman
• Easy on — /caveman, "caveman mode", "less tokens"
• Easy off — "stop caveman" or "normal mode"
• Smart boundary — code, commits, PRs stay normal. Caveman English only
• Plugin support — available in Claude Code marketplace

Install

npx skills add JuliusBrussee/caveman

Before / After

| 🗣️ Normal Claude (69 tokens) | 🪨 Caveman Claude (19 tokens) |
|---|---|
| "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle..." | "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo." |

Same fix. 75% less word. Brain still big.

What gone

| Thing | Status |
|-------|--------|
| Articles (a, an, the) | 💀 Gone |
| Filler words | 💀 Gone |
| "Sure I'd be happy to" | 💀 Dead |
| "It might be worth considering" | 💀 Extinct |
| Technical accuracy | 🧠 100% kept |
| Code blocks | ✍️ Normal |

One rock. That it. ⭐