caveman-install

Caveman Plugin Installation Guide

Caveman is a Claude Code plugin that reduces output tokens ~65% by enforcing terse, article-free communication. This skill covers install, verify, configure, and uninstall on Windows.

Quick Install

Windows (PowerShell 5.1+)

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

If execution policy blocks it:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

WSL / Git Bash

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

Claude Code Only (Manual)

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

What Gets Installed

1. Plugin — ~/.claude/plugins/marketplaces/caveman/
2. Hooks — Two hooks registered in ~/.claude/settings.json:
   • SessionStart: node src/hooks/caveman-activate.js — reads mode from ~/.claude/.caveman-active, injects activation prompt
   • UserPromptSubmit: node src/hooks/caveman-mode-tracker.js — tracks mode changes, appends context to user prompts
3. Hook files — ~/.claude/hooks/caveman-activate.js, caveman-mode-tracker.js, caveman-stats.js, caveman-config.js
4. Statusline — PowerShell script caveman-statusline.ps1 for [CAVEMAN] badge in Claude Code status bar
5. Flag file — ~/.claude/.caveman-active stores current mode (default: full)

Verify Installation

Three checks:

1. List detected agents:

   node ~/.claude/plugins/marketplaces/caveman/bin/install.js --list
   

2. Test in Claude Code: Type /caveman. Response should be terse fragments.

3. Check flag file:

   cat ~/.claude/.caveman-active
   # expected: full
   

4. Check settings.json hooks: Look for caveman-activate.js and caveman-mode-tracker.js in hooks section.

Statusline Setup

The statusline badge shows [CAVEMAN] (orange) in the Claude Code status bar. After first /caveman-stats run it appends a savings counter like [CAVEMAN] ⛏ 12.4k.

Add to ~/.claude/settings.json (or project .claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "powershell -ExecutionPolicy Bypass -File \"C:\\Users\\twc\\.claude\\plugins\\marketplaces\\caveman\\src\\hooks\\caveman-statusline.ps1\""
  }
}

Adjust path if your Windows username differs. The .ps1 script lives under the caveman plugin directory.

Modes

Command	Mode	Effect
/caveman	full (default)	Drop articles, fragments OK, short synonyms
/caveman lite	lite	Mild compression, keep most structure
/caveman ultra	ultra	Maximum compression, near-telegraphic
/caveman wenyan	wenyan-lite/full/ultra	Classical Chinese style
stop caveman / normal mode	off	Revert to normal output

Troubleshooting

Hooks not firing

1. Check claude is on PATH: which claude
2. Check ~/.claude/settings.json has hooks with caveman-activate.js
3. Check ~/.claude/.caveman-active exists with content full
4. Restart Claude Code — SessionStart hook only fires on session start

Windows-specific

• Use install.ps1, not install.sh, for hook wiring
• PowerShell 5.1 minimum: check $PSVersionTable.PSVersion
• If irm | iex blocks on execution policy: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

settings.json mangled

1. Check backup at ~/.claude/settings.json.bak
2. Restore from backup or version control
3. Re-run installer with --force

Managed environment (no hooks)

Use rule-file-only path:

node ~/.claude/plugins/marketplaces/caveman/bin/install.js --with-init --only cursor

Drops .cursor/rules/caveman.mdc etc. into repo. No hooks, no global config.

Uninstall

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

Removes hooks, plugin, flag file. Does NOT remove:

• Skills installed via npx skills add
• Per-repo rule files from --with-init (delete manually)

Useful Flags

Flag	Purpose
--dry-run	Preview commands, write nothing
--all	Install everything detected
--minimal	Plugin only, no hooks
--only <id>	One agent only (e.g. --only claude)
--force	Re-run even if already installed
--with-init	Drop always-on rule files into current repo
--with-mcp-shrink="<cmd>"	Register caveman-shrink MCP proxy (opt-in)
--list	Print full agent matrix and exit