claude-pulse

claude-pulse

A real-time usage monitor for Claude Code — see your limits at a glance.

_{10 built-in themes with colour-coded bars that shift green → yellow → red as usage increases}

_{Rainbow animation — enable with /pulse animate on or --animate on}

_{Automatic update notification — appears when a new version of claude-pulse is available}

_{Claude Code update indicator — appears when a Claude Code update is available (just a notification, run claude update yourself)}

---

Works with any Claude subscription — Pro (£18/mo), Max 5x (£90/mo), or Max 20x (£180/mo). No API key required. Auto-detects your plan and reflects the exact usage shown on claude.ai/settings/usage.

---

What is this?

claude-pulse adds a live status bar to the bottom of your Claude Code CLI window showing:

• Session usage — how much of your current 5-hour block you've used
• Time remaining — countdown until your session resets
• Weekly usage — your 7-day rolling usage across all models
• Opus / Sonnet usage — per-model weekly limits (auto-shows when you have usage)
• Context window — how full Claude's memory/context is (with colour-coded bar)
• Model name — which model is active (Opus 4.6, Sonnet 4.5, etc.)
• Effort level — shows low/med/high/max when Claude Code sets it (v2.1.68+)
• Worktree branch — shows the active worktree branch name (v2.1.69+)
• Plan tier — auto-detected (Pro, Max 5x, Max 20x)
• Extra credits — auto-shows when you have credits enabled in https://claude.ai/settings/usage

No guesswork. No scanning log files. It pulls the exact same numbers shown on claude.ai/settings/usage via Anthropic's OAuth API — the same authentication you already use when logged into Claude Code.

Quick Start — /pulse

Once installed, just type /pulse in Claude Code. That's it. A guided wizard walks you through picking a theme, text colour, and animation settings — no commands to remember.

/pulse          — opens the interactive setup wizard
/pulse show     — preview all themes and text colours
/pulse ocean    — jump straight to a theme by name
/pulse config   — see your current settings
/pulse update   — pull the latest version from GitHub

Everything below can also be configured via /pulse — the CLI flags are there if you prefer them.

---

Features

Colour-coded progress bars

The bars change colour based on your usage level so you can tell at a glance how close you are to your limits:

Usage	Colour	Meaning
0-49%	Green	Plenty of headroom
50-79%	Yellow	Getting warm
80%+	Red	Close to the limit

This applies to all bars — session, weekly, opus, sonnet, context window, and extra credits.

10 Built-in Themes

Each theme uses accent colours for text and colour-coded progress bars that shift from low to mid to high based on your usage. The rainbow theme applies a full-spectrum colour gradient across the entire status line.

Preview them live in Claude Code with /pulse show, or from the command line with python claude_status.py --show-themes.

Rainbow Animation

Turn on animation and rainbow colours flow across your status bar while Claude is active:

# Enable rainbow animation (works with any theme)
python claude_status.py --animate on

# Turn it off — static theme colours
python claude_status.py --animate off

The animation uses Claude Code's ultrathink rainbow palette — the same 7-colour spectrum (red, orange, yellow, green, blue, indigo, violet) with smooth interpolation and a breathing shimmer effect. It's purely refresh-based — no hooks, no background processes, no daemons. Each status line refresh renders a new frame (~150ms while active). Animation is off by default — enable it via /pulse setup or --animate on.

Context Window & Model Name

See how full Claude's context/memory is and which model you're running, right in the status bar:

Session ━━━━━━━━ 12% 3h 40m | Weekly ━━━━━━━━ 12% | Context ━━━━━━━━ 42% | Max 20x | Opus 4.6