feat: optional SessionStart hook + visible statusline badge pattern

Adds hooks/caveman-activate.js — an optional Claude Code SessionStart
hook users can wire up via ~/.claude/settings.json to auto-load the
caveman ruleset at session start. The hook also writes a flag file
at ~/.claude/.caveman-active that a statusline script can read to
render a persistent [CAVEMAN] badge.

Why: SessionStart hook stdout is injected as hidden system-reminder
context — useful for Claude, invisible to users in the terminal. This
means users have no way to confirm the hook fired. The flag file is
a minimal bridge between 'the hook ran' and 'the statusline can
prove it', giving users persistent visual confirmation that caveman
mode is loaded.

This is a pure addition:

- New file: hooks/caveman-activate.js (~30 lines, no dependencies
  beyond Node.js stdlib)
- README section 'Optional: SessionStart Hook + Visible Mode Badge'
  documents both the hook install and the statusline snippet
- Marked Claude Code-only since it relies on Claude Code's hooks
  and statusline mechanisms — Cursor/Codex/other users can ignore
- No existing files changed except README

If you don't wire up the hook, nothing changes. Skill install works
exactly as before.
This commit is contained in:
Jimmy CrakCrn
2026-04-09 07:37:18 -05:00
parent 26c25e39b3
commit a62d6602c3
2 changed files with 85 additions and 0 deletions
+51
View File
@@ -156,6 +156,57 @@ Codex:
Install once. Use in all sessions after that. One rock. That it.
### Optional: SessionStart Hook + Visible Mode Badge
If you want Claude Code to auto-load caveman rules at session start **and** show a persistent `[CAVEMAN]` badge in your statusline (so you can see at a glance that caveman mode is loaded), wire up the hook in `hooks/caveman-activate.js`.
> [!NOTE]
> This is a **Claude Code-only** optional addition. The core skill install above works fine without it. Skip this section if you're using Cursor, Codex, or another agent.
**1. Install the hook** — copy `hooks/caveman-activate.js` to `~/.claude/hooks/caveman-activate.js`, then add it to `~/.claude/settings.json`:
```json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "node \"~/.claude/hooks/caveman-activate.js\"",
"statusMessage": "Loading caveman mode..."
}
]
}
]
}
}
```
The hook writes a flag file at `~/.claude/.caveman-active` and emits the caveman ruleset reminder as SessionStart context.
**2. Add the badge to your statusline** — in your Claude Code statusline script, check for the flag file and prepend a badge:
```js
const fs = require('fs');
const path = require('path');
const os = require('os');
// ...existing statusline logic...
let cavemanBadge = '';
const cavemanFlag = path.join(os.homedir(), '.claude', '.caveman-active');
if (fs.existsSync(cavemanFlag)) {
cavemanBadge = '\x1b[1;38;5;208m[CAVEMAN]\x1b[0m │ ';
}
process.stdout.write(`${cavemanBadge}${rest_of_your_statusline}`);
```
Restart Claude Code and an orange `[CAVEMAN]` badge sits in your statusline for the entire session.
**Why a flag file?** `SessionStart` hook stdout is injected as hidden system-reminder context — useful for Claude, invisible to users. The statusline runs as a separate process and can't see that context. A flag file is the simplest bridge between "the hook ran" and "the statusline can prove it."
## Usage
Trigger with:
+34
View File
@@ -0,0 +1,34 @@
#!/usr/bin/env node
// caveman — optional Claude Code SessionStart activation hook
//
// When wired into ~/.claude/settings.json as a SessionStart hook:
// - Writes a flag file at ~/.claude/.caveman-active so a statusline
// script can prove caveman mode is loaded (see README for the badge
// snippet — SessionStart stdout is otherwise invisible to users)
// - Emits a short ruleset reminder as SessionStart context
//
// This is a pure addition — if you don't wire it up, nothing changes.
// Install instructions: see the "Optional: SessionStart Hook" section
// in README.md.
const fs = require('fs');
const path = require('path');
const os = require('os');
const flagPath = path.join(os.homedir(), '.claude', '.caveman-active');
try {
fs.mkdirSync(path.dirname(flagPath), { recursive: true });
fs.writeFileSync(flagPath, String(Date.now()));
} catch (e) {
// Silent fail -- flag is best-effort, don't block the hook
}
process.stdout.write(
"CAVEMAN MODE ACTIVE. Rules: Drop articles/filler/pleasantries/hedging. " +
"Fragments OK. Short synonyms. Pattern: [thing] [action] [reason]. [next step]. " +
"Not: 'Sure! I'd be happy to help you with that.' " +
"Yes: 'Bug in auth middleware. Fix:' " +
"Code/commits/security: write normal. " +
"User says 'normal' or 'stop caveman' to deactivate."
);