claudecode-statusline

A one-command setup for a richly decorated Claude Code statusline with Caveman mode baked in. Interactive installer lets you pick all components or only the ones you want.

What you get

[🪨 CAVEMAN] │ 📁 my-project 🌿 main │ 🤖 Claude Sonnet 4.6 │ CTX ████░░░░ 42% │ ⚡ ▄ MEDIUM │ 5h ████░░░░ 42% used 58% rem ↺ 1h 22m │ 7d ██░░░░░░ 85% used 15% rem ↺ 3d 7h

Rate limit bars use color-coded severity for both values:

• Used % — green (low) → yellow (mid) → red (high usage)
• Rem % — green (plenty left) → yellow → red (almost none left)

Prerequisites

Quick start

macOS / Linux

git clone https://github.com/FahimFBA/claudecode-statusline.git
cd claudecode-statusline
chmod +x install.sh
./install.sh

Then restart Claude Code.

Windows (PowerShell)

git clone https://github.com/FahimFBA/claudecode-statusline.git
cd claudecode-statusline
powershell -ExecutionPolicy Bypass -File install.ps1

Then restart Claude Code.

Interactive installer

When you run the installer it will ask:

How do you want to install?

  1) Full install  -- all components, replaces existing statusline
  2) Custom        -- choose which components to include

Choice [1/2, default=1]:

If you choose 2, you'll see a numbered menu:

Available components:

  1) Caveman badge      🪨 CAVEMAN:FULL
  2) Project + branch   📁 my-project 🌿 main
  3) Model name         🤖 Claude Sonnet 4.6
  4) Context window     CTX ████░░░░ 42%
  5) Effort level       ⚡ ▄ MEDIUM
  6) Hourly limit (5h)  5h ████░░░░ 42% used · 58% rem ↺ 1h 22m
  7) Weekly limit (7d)  7d ██░░░░░░ 85% used · 15% rem ↺ 3d 7h
  8) Token savings      🪨 ~42% tokens saved

Numbers to include (e.g. 2 3 4 6 7), or 'all' [default=all]:

Enter the numbers you want separated by spaces. Your existing statusLine in settings.json is shown before you choose, so you can decide whether to replace it or build a custom one.

What the installer does

1. Copies hook scripts to ~/.claude/hooks/
2. Merges settings into ~/.claude/settings.json (backs up existing file first)
3. Installs the Caveman plugin via claude plugins install caveman --marketplace caveman

Existing settings are merged, not overwritten — your other config survives.

Caveman mode commands

Intensity levels

Files

claudecode-statusline/
├── hooks/
│   ├── caveman-activate.js      # SessionStart hook — activates caveman mode
│   ├── caveman-config.js        # Shared config resolver + safe flag I/O
│   ├── caveman-mode-tracker.js  # UserPromptSubmit hook — tracks mode changes
│   ├── caveman-stats.js         # Token usage stats engine
│   ├── caveman-statusline.sh    # Statusline renderer (bash)
│   └── package.json             # CommonJS marker
├── settings.template.json       # Reference settings (paths replaced by installer)
├── install.sh                   # macOS / Linux installer
├── install.ps1                  # Windows PowerShell installer
└── README.md

Customising the statusline

Re-run the installer and choose option 2 to pick which components to show.

Or edit ~/.claude/hooks/caveman-statusline.sh directly after install. The append function controls segment order — comment out any segment you don't want.

Each component can also be toggled via environment variables in the statusLine command (the installer writes these automatically when you use option 2):

To change caveman default mode, set the environment variable before starting Claude Code:

export CAVEMAN_DEFAULT_MODE=lite   # lite | full | ultra | off

Or create ~/.config/caveman/config.json:

{ "defaultMode": "lite" }

Uninstall

Remove the hook scripts:

rm ~/.claude/hooks/caveman-*.js ~/.claude/hooks/caveman-statusline.sh

Remove the hooks, statusLine, enabledPlugins, and extraKnownMarketplaces keys from ~/.claude/settings.json.

Credits

• Caveman plugin by JuliusBrussee — the underlying caveman mode engine
• Statusline and installer by FahimFBA