Install caveman

One install. Works for every AI coding agent on your machine.

If just want it to work, run the one-liner. If want to know what gets touched, scroll down.

One-liner

macOS / Linux / WSL / Git Bash

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

Windows (PowerShell 5.1+)

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

Piping a script straight into a shell runs it sight-unseen. If you'd rather read it first, download then run: curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh -o install.sh (review it) && bash install.sh. The installer downloads hook files from a pinned release tag and verifies them against a committed SHA-256 manifest before writing.

What it does:

• Auto-detects every supported agent installed on your machine (Claude Code, Cursor, Codex, etc.).
• For each one, runs that agent's native install path (plugin / extension / rule file / npx skills add).
• Wires Claude Code hooks and statusline badge on top. (caveman-shrink MCP middleware is opt-in via --with-mcp-shrink — see flag table below.)
• Skips anything you don't have. Safe to re-run. ~30 seconds end-to-end.

Want to preview before installing? Use --dry-run:

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

Per-agent install

If you want to install for one agent (or want to know exactly what command runs under the hood), use the table below. Every row also works as --only <id> to the unified installer.

"Soft probe" = installer won't auto-detect these without --only <id> because there's no reliable always-on signal (Copilot subscription state is auth-gated; the others have no CLI / config-dir-only). Pass the flag when you want them.

For "auto-activates? No" agents, type /caveman once per session (or use natural-language triggers like "talk like caveman", "caveman mode").

Finding a profile slug for npx skills add ... -a <profile>? Either read the table above, or print the live matrix from the installer:

# Either of these works (install.sh / install.ps1 are thin shims that
# forward all flags to bin/install.js):
bash install.sh --list             # macOS / Linux / WSL, from a local clone
pwsh install.ps1 --list            # Windows / PowerShell, from a local clone
node bin/install.js --list         # any platform, from a local clone
npx -y github:JuliusBrussee/caveman -- --list   # no clone needed

Each row prints the agent id, profile slug (where applicable), and whether it was auto-detected on your machine. Full agent matrix (with detection rules) is also defined in bin/install.js under the PROVIDERS array.

Manual install (no curl | bash)

If you'd rather see exactly what runs:

# Clone the repo
git clone https://github.com/JuliusBrussee/caveman.git
cd caveman

# Preview every command the installer would run
node bin/install.js --dry-run --all

# Inspect the agent matrix
node bin/install.js --list

# Install for everything detected
node bin/install.js --all

Useful flags:

Always-on rules

For agents without a hook system (Cursor, Windsurf, Cline, Copilot, and friends), the always-on path is a static rule file. Two ways:

# Drop rule files into the current repo
node bin/install.js --with-init

# Or pull the rule body straight in (manual)
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/src/rules/caveman-activate.md \
  > .cursor/rules/caveman.mdc   # or .windsurf/rules/caveman.md, .clinerules/caveman.md, .github/copilot-instructions.md

--with-init writes the rule into every supported per-agent location it can detect (.cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, .opencode/AGENTS.md, AGENTS.md). It also installs the OpenClaw workspace bootstrap (skill folder + SOUL.md marker block) when ~/.openclaw/workspace/ exists. Single source: src/rules/caveman-activate.md.

Verify

After install, three quick checks:

1. See what got installed.

node bin/install.js --list

You should see ~30 rows. Detected agents are marked. Anything you wanted but isn't marked → not detected (likely the binary isn't on PATH).

2. Talk to Claude Code.

Open Claude Code, type /caveman. Response should be terse fragments — "Got it. Caveman mode on." or similar. Try a real question: "What is closures in JS?" — answer should drop articles and read like grunts.

3. Check the flag file.

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"
# expected output: full

If it's missing or empty, the SessionStart hook didn't fire. See troubleshooting below.

Statusline should show [CAVEMAN] (orange) at the bottom of Claude Code. After your first /caveman-stats run it appends a savings counter like [CAVEMAN] ⛏ 12.4k.

Uninstall

npx -y github:JuliusBrussee/caveman -- --uninstall

What it removes:

• Caveman hook entries from $CLAUDE_CONFIG_DIR/settings.json (default ~/.claude/; matched by the substring caveman).
• Hook files in $CLAUDE_CONFIG_DIR/hooks/ (caveman-activate.js, caveman-mode-tracker.js, caveman-stats.js, caveman-config.js, caveman-statusline.{sh,ps1}, plus the dir's package.json marker).
• The Claude Code plugin and the Gemini CLI extension (if installed).
• The opencode native plugin (~/.config/opencode/plugins/caveman/, the plugin and mcp.caveman-shrink entries from opencode.json, our skill/agent/command files, the caveman block from AGENTS.md, and the opencode flag file).
• The OpenClaw workspace skill folder and the marker-fenced block from ~/.openclaw/workspace/SOUL.md (when present).
• The .caveman-active flag file.

What it does not remove:

• Skills installed via npx skills add — the skills CLI manages those. Run npx skills remove caveman (or use your IDE's skill manager).
• Per-repo rule files written by --with-init (.cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, .opencode/AGENTS.md, AGENTS.md). Delete by hand if you want.

Troubleshooting

"Install script broke. What now?"

Open your agent in this repo and say:

"Read CLAUDE.md and INSTALL.md. Install caveman for me."

Agent read repo. Agent run install. Caveman make agent talk less — agent first job is install caveman to talk less. Snake eat tail.

Still broken? Open an issue.

"I ran the installer but Claude Code isn't talking caveman."

1. Run node bin/install.js --list — confirm claude is on the detected list. If not, claude isn't on PATH. Fix that first.
2. Open $CLAUDE_CONFIG_DIR/settings.json (default ~/.claude/settings.json) and look for "hooks" containing caveman-activate.js and caveman-mode-tracker.js. If missing, re-run with --force.
3. Check $CLAUDE_CONFIG_DIR/.caveman-active exists with content full. If not, the SessionStart hook silent-failed — check $CLAUDE_CONFIG_DIR/hooks/ for the JS files and try node $CLAUDE_CONFIG_DIR/hooks/caveman-activate.js < /dev/null to see if it errors.
4. Restart Claude Code. The SessionStart hook only fires on session start, not mid-session.

"Hooks failing on Windows."

• Use install.ps1, not install.sh. Git Bash works for the shell version, but the hook side wires PowerShell counterparts (caveman-statusline.ps1).
• PowerShell 5.1 minimum. Check with $PSVersionTable.PSVersion.
• If irm | iex blocks on execution policy: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass for the install session, then re-run.
• Long-running issues: see docs/install-windows.md in the repo for manual fallback.

"My settings.json got mangled."

The installer uses a JSONC-tolerant parser (bin/lib/settings.js) so comments and trailing commas don't crash the merge. It also runs validateHookFields() before every write so a malformed hook can't poison the file. If something still went wrong:

1. Check for a backup at $CLAUDE_CONFIG_DIR/settings.json.bak (installer writes one before any merge).
2. If no backup, restore from your shell history or version control.
3. File an issue with the broken settings.json content (redacted) — that file passing validation but breaking Claude Code is a bug we want to fix.

"I'm in a managed env where I can't install hooks."

Use the rule-file-only path. Hooks are Claude Code-specific; everything else works via static rule files:

# Just install for one agent, no Claude hooks
node bin/install.js --only cursor

# Or write rule files into the current repo only (no global state)
node bin/install.js --with-init --only cursor --only windsurf

This drops .cursor/rules/caveman.mdc (and friends) into your repo. No hooks, no global config, nothing outside the repo.

"npx skills add errored on a profile slug."

The profile slug must exist in vercel-labs/skills. If a row in the table above 404s, the upstream profile was renamed or removed — open an issue, we'll update.

Privacy

The installer doesn't phone home. It writes to:

• $CLAUDE_CONFIG_DIR (default ~/.claude/) — hooks, flag file, settings.json merge.
• Each agent's own config location — Cursor's .cursor/rules/, Windsurf's .windsurf/rules/, opencode's ~/.config/opencode/, etc.
• Your current working directory (only with --with-init) — repo-local rule files.
• ~/.openclaw/workspace/ (only with --only openclaw or --with-init when OpenClaw is detected) — the one --with-init side-effect outside the cwd.

No telemetry. No analytics. Run from a clone or via npx, the installer's own code makes no network calls — files are copied locally. One exception: run detached from any checkout (the rare curl-fallback path), it downloads the hook files from raw.githubusercontent.com pinned to an immutable release tag and verifies each against a SHA-256 manifest before wiring anything. Network requests also happen indirectly through the per-agent CLIs it shells out to — claude plugin marketplace add, claude plugin install, gemini extensions install, npm view caveman-shrink, and npx -y skills add. Each fetches from its own registry (Anthropic / GitHub / npm). Source: bin/install.js. After install: zero network calls, ever — full statement in SECURITY.md.

---

Stuck? Open an issue: https://github.com/JuliusBrussee/caveman/issues