| name | ralph-caveman |
| description | Enable or disable cavemanMode on a Ralph PRD. When enabled, Ralph compresses progress files via caveman-compress (reducing input tokens on every iteration), runs a one-time compression pass on AGENTS.md/CLAUDE.md during /ralph-worktree setup, and uses caveman-style terse chat output when running headless. Commits, decision files, and AGENTS.md additions during a run always stay in full prose. Use when the user says 'run this with /ralph-caveman', 'enable caveman', 'turn on compression', 'disable caveman', or when /ralph-pilot is recommending compression separately from model delegation. Triggers on: /ralph-caveman, ralph-caveman, enable caveman, disable caveman, turn on compression, turn off compression. |
| version | 1.0 |
/ralph-caveman
Small focused skill that toggles cavemanMode on a Ralph PRD's prd.json. Gets explicit user confirmation before flipping the flag.
This is one of two independent mode flags (modelHintMode is the other — see /ralph-modelhint). They are orthogonal and can be enabled independently.
Caveman is an output/input-compression style based on JuliusBrussee/caveman: "why use many token when few do trick." It drops articles, filler words, and hedging from prose while preserving code, file paths, commands, and all technical substance.
What cavemanMode does
When cavemanMode: true on prd.json, three things change:
-
Compressed progress history. ralph.sh runs caveman on rotated progress-N.txt files after each rotation. Future iterations that read prior progress consume fewer input tokens. If caveman is not installed on PATH, this is a silent no-op — no failure.
-
Compressed context files at worktree setup. /ralph-worktree runs a one-time caveman pass on every AGENTS.md and CLAUDE.md file in the worktree (excluding node_modules / .git). These files load on every session start, so compression here is high-leverage.
-
Terse chat output when headless. When the run is not attached to ralph-tui (i.e., RALPH_TUI != 1), ralph.sh sets RALPH_HEADLESS=1 and writes it into the prompt preamble. Ralph (see prompt.md) then adopts caveman-style terse output for its streaming chat: drop articles, filler, hedging; fragments OK; code/paths/commands/numbers unchanged. When attached to ralph-tui, output stays in prose so a watching human can read along comfortably.
Always stays in full prose regardless of this flag:
- Commit messages (must be legible in
git log forever)
- Decision-gate files in
decisions/*.md (the user reads these to make a decision)
- AGENTS.md additions made during a run (future developers read these — existing content may be compressed by the setup pass, but new additions go in verbose)
- The Codebase Patterns section of progress.txt (future Ralph iterations read this)
When cavemanMode: false (the default), nothing is compressed and chat output is always prose.
When the user should enable this
Good candidates:
- Long-running PRDs where progress.txt grows large and gets rotated multiple times
- Worktrees with substantial AGENTS.md / CLAUDE.md files that load every iteration
- Any PRD where speed and token cost matter more than iteration-log readability
- Running headless via
/ralph-runner or background — nobody watching live, so terse output is pure savings
Bad candidates:
- PRDs with many decision gates (the decision files themselves are safe, but compressed surrounding context makes pilot monitoring harder)
- New workflows where you want pristine iteration logs for debugging
- When
caveman is not installed and the user doesn't want to install it — the compression steps become no-ops, so the only effect is terse output, which may not be worth it alone
Prerequisite — caveman installation
Caveman-compress is a Python CLI. If command -v caveman returns nothing, the compression steps silently no-op. The terse output still works because it's driven by prompt.md reading the preamble flag, not by the CLI.
Installation options (only needed if the user wants the compression benefit):
npx skills add JuliusBrussee/caveman/caveman-compress (cross-agent)claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman (installs the plugin globally, with the side effect of auto-activating caveman in every Claude Code session — don't use this if you want per-PRD scoping, the prd.json flag approach is cleaner)- From the local clone at
d:/caveman/caveman-compress/: cd d:/caveman/caveman-compress && pip install -e .
Check before promising the user compression will happen.
How to run this skill
Step 1 — Identify the PRD
If the user named a task directory ("run console-v2 with /ralph-caveman"), use tasks/{name}/prd.json. If ambiguous or unnamed, list task dirs with a prd.json and ask.
Step 2 — Read current state
jq '{modelHintMode, cavemanMode, stories: (.userStories | length)}' tasks/{effort-name}/prd.json
command -v caveman >/dev/null 2>&1 && echo "caveman: installed" || echo "caveman: NOT installed"
Report current flag values and whether caveman is installed. If the user asked to enable and it's already enabled, say so and stop. Same for disable.
Step 3 — Assess fit (when enabling)
Quickly check:
- How many decision-gate stories are in the PRD? (>3 → note that monitoring will be harder)
- Is ralph-tui likely to be used for this run, or headless? (tui = terse output doesn't apply; headless = full benefit)
- Is there an existing progress.txt that's already large? (immediate compression win on rotation)
Step 4 — Get explicit confirmation
Ask the user in this shape:
This PRD has {N} stories. cavemanMode does three things:
- Compresses rotated progress-N.txt files (if caveman is installed: {yes|no})
- Compresses AGENTS.md / CLAUDE.md once during /ralph-worktree setup
(if caveman is installed: {yes|no})
- Uses terse caveman-style chat output when Ralph runs headless (ralph-tui
attached → still prose)
Always-prose carve-outs: commits, decisions/*.md, AGENTS.md additions during
runs, and the Codebase Patterns section of progress.txt.
{If caveman NOT installed: "Note — caveman isn't on PATH, so only the terse
headless-output behavior will actually take effect unless you install it
(npx skills add JuliusBrussee/caveman/caveman-compress)."}
{If >3 decision gates: "Note — this PRD has {D} decision gates. Terse iteration
output can make mid-run monitoring harder; the decision files themselves stay in
prose."}
Confirm enable, or reply "no" / "cancel" to leave it off.
Proceed only on explicit yes.
Step 5 — Flip the flag
jq '.cavemanMode = true' tasks/{effort-name}/prd.json > /tmp/prd.tmp && \
mv /tmp/prd.tmp tasks/{effort-name}/prd.json
jq '.cavemanMode = false' tasks/{effort-name}/prd.json > /tmp/prd.tmp && \
mv /tmp/prd.tmp tasks/{effort-name}/prd.json
Step 6 — Optional: one-time compression pass now
If the user just enabled cavemanMode AND the worktree already exists AND caveman is installed, offer to run the one-time AGENTS.md / CLAUDE.md compression now (rather than waiting for it to happen the next time /ralph-worktree runs):
Want me to run the one-time caveman pass on AGENTS.md / CLAUDE.md files in the
worktree right now? It'll save input tokens starting with the next iteration.
(Originals are preserved as *.original.md.) Reply yes or no.
If yes:
cd {worktree-path}
find . -name 'AGENTS.md' -not -path '*/node_modules/*' -not -path '*/.git/*' -print0 | \
xargs -0 -I {} caveman "{}" 2>&1
[ -f CLAUDE.md ] && caveman CLAUDE.md 2>&1
Report the total tokens saved (caveman prints this per file).
Step 7 — Report
cavemanMode: {true|false} for tasks/{effort-name}/prd.json.
{If true and compression ran: Compressed {N} files, saved ~{T} tokens.}
{If true and Ralph not yet launched: Next run will also compress progress files
after rotation and use terse output when headless.}
{If Ralph is currently running: the flag takes effect on the NEXT iteration;
the in-flight iteration runs with the previous setting.}
Interaction with /ralph-modelhint
modelHintMode is a completely separate flag that controls delegation and parallelism. This skill does NOT touch it. If the user asks for both ("enable /ralph-modelhint and /ralph-caveman"), run both skills in sequence — each asks its own confirmation.
/ralph-pilot §11 handles the combined recommendation flow when both are being considered together.
Anti-patterns
- Flipping the flag without confirmation. Always ask.
- Promising compression without checking that caveman is installed. If it's not, say so — the terse-output behavior still works, but the compression benefit requires the CLI.
- Compressing anything on the don't-compress list. Never run caveman on
decisions/*.md, active prd.md, prd.json, or git-tracked commit message drafts. If unsure, don't.
- Installing the caveman plugin globally to "make this work". The plugin's SessionStart hook activates caveman for every Claude Code session on this machine, not just Ralph. Per-PRD scoping via this flag is cleaner; install
caveman-compress as a standalone CLI instead if the user wants the compression benefit.
- Flipping while Ralph is mid-iteration. Safe in principle (takes effect next iteration), but note it to the user.
