---
title: Caveman Configuration
created: 2026-05-03
status: active
type: protocol
applied_by: claude-code-coo
---

# Caveman Configuration

## Date applied
2026-05-03 (Sydney AEST, ~12:13)

## Level
**lite** (global default)

Lite keeps full sentences but cuts pleasantries, hedging, filler ("just", "really", "basically"), and the "Sure! Happy to help!" preamble. It does NOT drop articles or use fragments — that's `full` or `ultra`.

## Agents configured
| Agent | Status | Reason |
|---|---|---|
| Claude Code | ✅ installed | Plugin `caveman@caveman` from `JuliusBrussee/caveman` marketplace + SessionStart/UserPromptSubmit hooks + statusline |
| Cowork (Claude Desktop) | ⏭️ skipped | Not in caveman's supported-agents matrix. Cowork terseness already governed by Rocky's existing project instructions ("Direct. Terse. No fluff.") |
| Hermes | ⏭️ skipped | Not in caveman's supported-agents matrix. Adding `level: lite` to `~/.hermes/config.yaml` would do nothing — Hermes doesn't read it. Hermes terseness needs a separate mechanism (its own SOUL/USER prompt, AI Team Protocol). Per HQ instruction: "skip the Hermes gateway restart for now" — so the gateway was not restarted; no config change applied to Hermes |
| Other CLIs (gemini, codex, cursor, windsurf, cline, aider, goose, qwen, etc.) | ⏭️ not detected | None on PATH. Single-target install on this machine |

## Files modified
| Path | Change |
|---|---|
| `~/.claude/settings.json` | `enabledPlugins['caveman@caveman']: true` added; `hooks.SessionStart` + `hooks.UserPromptSubmit` wired; `statusLine` set to `bash ~/.claude/hooks/caveman-statusline.sh` |
| `~/.claude/settings.json.bak` | Pre-edit backup created automatically by hooks-install.sh |
| `~/.claude/hooks/` | 6 files added: `caveman-config.js`, `caveman-activate.js`, `caveman-mode-tracker.js`, `caveman-stats.js`, `caveman-statusline.sh`, `package.json` |
| `~/.claude/.caveman-active` | Mode flag file (initial value: `lite`) |
| `~/.bashrc` | Appended `export CAVEMAN_DEFAULT_MODE=lite` |
| `C:\Users\mclou\AppData\Roaming\caveman\config.json` | Created with `{"defaultMode": "lite"}` |
| Marketplace cache | `JuliusBrussee/caveman` cloned to Claude Code's plugin marketplace cache |

## NOT installed (deliberately, defense-in-depth)
- **caveman-shrink MCP middleware** — not installed. Per HQ's "test on Claude Code first" staged-caution signal. The middleware compresses tool descriptions in `tools/list`/`prompts/list`/`resources/list` MCP responses. Review found it clean (narrow scope: only description fields in list responses, doesn't touch tool call payloads, no phone-home), but it's an additive optimization not required for the stated goal. To add later: `claude mcp add caveman-shrink -- npx -y caveman-shrink`.
- **Per-repo IDE rule files** (`--with-init`) — not run. No `.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`, `.github/copilot-instructions.md`, or `AGENTS.md` written. The HQ-Vault and rateright-growth-deploy repos already have CLAUDE.md / AGENTS.md governance — re-running with `--with-init` inside a specific repo would only matter if that repo wanted always-on caveman.

## How to change level later

**Persistent (config file — survives shell + GUI launches):**
```
node ~/.claude/hooks/caveman-config.js  # has CLI helpers; or edit directly:
echo '{"defaultMode":"ultra"}' > "$APPDATA/caveman/config.json"
```

**Persistent (env var — affects shells that source .bashrc):**
Edit `~/.bashrc` and change `export CAVEMAN_DEFAULT_MODE=lite` to `ultra`/`full`/`off`/etc.

**Per-session (in-conversation):**
- `/caveman ultra` — switch this session to ultra
- `/caveman lite` — switch back to lite
- `/caveman off` — disable for this session
- "stop caveman" or "normal mode" — natural-language disable

## Spec deviation flagged
HQ's spec instructed `export CAVEMAN_LEVEL=lite` and `CAVEMAN_LEVEL=ultra`/`normal` for changes. **The actual env var caveman reads is `CAVEMAN_DEFAULT_MODE`, not `CAVEMAN_LEVEL`.** The latter is silently unread. This doc reflects the correct name. The `~/.bashrc` line was written with the correct name.

Valid modes: `off`, `lite`, `full`, `ultra`, `wenyan-lite`, `wenyan`, `wenyan-full`, `wenyan-ultra`, plus three independent skills: `commit`, `review`, `compress`.

## Verification
- `getDefaultMode()` resolves to `lite` via the config file (verified)
- SessionStart hook runs cleanly (exit 0, emits SKILL.md content)
- UserPromptSubmit hook handles `/caveman <level>` correctly (flag file updates)
- Statusline renders `[CAVEMAN:LITE]` after mode switch (verified)
- settings.json backup at `~/.claude/settings.json.bak` (1568 bytes, pre-edit state preserved)

## Activation in this session
Existing Claude Code sessions started before the install do NOT automatically pick up the new hooks — Claude Code reads `settings.json` at session start. Restart Claude Code (or start a fresh session) to activate. Cowork is unaffected. The current session this protocol was authored from is therefore still operating in the previous output style.

## Token-savings benchmark
Caveman README claims ~75% output token reduction at full level, ~46% input token reduction with caveman-compress (not installed here). Lite is more conservative — published examples show ~30-40% reduction by dropping pleasantries/hedging/filler while keeping full sentences. No local measurement run yet.

## Uninstall
1. `claude plugin uninstall caveman@caveman`
2. `claude plugin marketplace remove caveman`
3. `rm -rf ~/.claude/hooks/caveman-*.{js,sh} ~/.claude/hooks/package.json ~/.claude/.caveman-active`
4. Restore `~/.claude/settings.json` from `~/.claude/settings.json.bak` if needed
5. Remove `export CAVEMAN_DEFAULT_MODE=lite` from `~/.bashrc`
6. Remove `C:\Users\mclou\AppData\Roaming\caveman\` directory

## Security review summary
Pre-install review on 2026-05-03 found:
- Repo health solid (52K stars, 2.8K forks, MIT, active commits, 9+ contributors with multi-commits, closed issue #262 added SHA-256 integrity verification — defensive)
- `install.sh`: only fetches `raw.githubusercontent.com/JuliusBrussee/caveman/main/`, no third-party domains, no sudo/crontab/systemctl, idempotent, has `--dry-run`, backs up settings.json before edit
- Hook scripts: local-only, no network, write only to `~/.claude/`, use `execFileSync` (no shell injection), 5s timeouts, `safeWriteFlag` is symlink-safe
- `caveman-shrink`: narrow scope (only description fields in list responses), no payload logging, no phone-home (not installed anyway)
- `SKILL.md`: pure prompt content, no injection patterns, includes "Auto-Clarity" section telling Claude to drop caveman style for security warnings + irreversible actions
- `caveman-statusline.sh`: explicit hardening — refuses symlinks, caps reads at 64 bytes, strips chars outside `[a-z0-9-]`, whitelists mode strings

Full review trail in this session's transcript.