claude-pulse

---

What is this?

A single-file Python status bar for Claude Code that shows everything you need at a glance — no API key required, zero dependencies, works with your existing Claude Code subscription.

Session ━━━───────── 27% 2h 53m | Weekly ━━━━━━━━━─── 73% R:Fri 3pm | Fable ━━───────── 18% | Context ━━━━──────── 35% | $38.75 | +142 -37 | Opus 5 | Effort: XHigh | ⚡fast | main

What's new in 3.3.0

• Sonnet 5 priced at its now-permanent $2/$10 rate — Anthropic cancelled the scheduled September increase to $3/$15. Historical turns are priced by their own date either way, so a promo lapsing can never retroactively inflate the cost widgets.
• GitLab merge requests render as !N via the pr.kind stdin field (Claude Code 2.1.234+); GitHub PRs keep #N.
• MiniMax quota works on Windows — npm installs mmx as a .cmd shim that subprocess won't auto-resolve; the call now goes through a PATH lookup (thanks @PFalko, #50).
• The repaint timer heals itself — a focus timer expiring on its own or a heartbeat going stale no longer leaves the 15s timer armed, and a heartbeat waking from idle arms it immediately.
• Self-hosted star chart — GitHub restricted the stargazers API to repo collaborators, so the README chart is rendered weekly by a workflow with the repo's own token and committed as static SVGs.
• Fable weekly cap — read from the model-scoped limits the API reports, so new models are picked up without a code change.
• Claude 5-era stdin fields — reasoning effort, ⚡fast mode, thinking state, active subagent, PR badge, and cache-hit ratio.
• Fixed: the refresh timer never worked. Every version up to 3.1.0 wrote a refresh key that Claude Code does not have, so it was silently ignored — animations, the heartbeat and the focus countdown froze whenever the session went idle. The real setting is refreshInterval, and it is now set only when something time-based is on screen.
• ~40% faster repaints (204ms → 118ms): claude --version and git rev-parse were both running on every repaint just to validate hourly caches.
• Per-model bars no longer invent data — Claude Pro reports null for the model-scoped windows, and 3.1.0 drew a hardcoded Sonnet 0% bar in that case.
• Zero API calls, for real — the per-model caps arrive on stdin, but 3.1.0 discarded them and re-fetched over OAuth. That call is gone.
• Two-line layout, rolling 7-day cost widget, CLAUDE_CONFIG_DIR support, exponential backoff on 429, and an update check that no longer nags forks forever.
• Corrupt state can't blank the bar — a truncated or hand-edited cache/settings file used to raise on the hot path. Every state read now degrades to a cache miss instead, and one malformed rate-limit field no longer discards the windows after it.
• Subagent panel rows via subagentStatusLine, a live agent counter from the SubagentStart/SubagentStop hooks, and an opt-in budget bar.
• The heartbeat is now opt-in — the [/] 42 tools 5m spinner is noise for most people, needs a hook, and kept the repaint timer alive. --show heartbeat brings it back.
• Peak hours removed.

Python floor is 3.8 — 3.1.0 advertised 3.6+ but did not parse below 3.12. Test suite: 21 → 204.

Features

Feature	Description
Session & Weekly bars	Colour-coded progress bars (green → yellow → red) for 5-hour session and 7-day weekly limits
Context window	Live context usage percentage with pressure warnings at 70%/90%
Cost tracking	Real-time session cost in your local currency (USD, GBP, EUR, + 25 more) with live exchange rates
Per-model weekly caps	Separate bars for Opus, Sonnet and Fable weekly budgets, read from the model-scoped limits the API reports. Shown only when your plan actually reports them
Effort & fast mode	Reasoning effort, written as Effort: Medium by default and colour-escalating with the level (--effort-format full/short for Medium/med), plus a ⚡fast badge while Opus fast mode is on
Subagent & PR	Active subagent name, plus an opt-in clickable PR badge with review state (OSC 8 hyperlink)
Cache efficiency	Opt-in indicator for the share of input served from cache — the clearest cost signal on stdin
Two-line layout	Split widgets across two rows with line1_widgets / line2_widgets
Subagent rows	Custom per-agent rows in the agent panel via subagentStatusLine — status, model, effort, a context bar from tokenCount/contextWindowSize, and elapsed time
Live agent counter	agents 3 live · 47/200 from SubagentStart/SubagentStop hooks, colour-escalating toward the caps
Budget bar	Spend against a ceiling you set with --budget to match your --max-budget-usd
Live heartbeat	Opt-in spinner with tool count and elapsed time — --show heartbeat plus --install-hooks
Git branch	Current branch name always visible
Model display	Shows which model is active (Fable, Opus, Sonnet, Haiku)
10 themes	default, ocean, sunset, mono, neon, pride, frost, ember, candy, rainbow
5 animation modes	off, rainbow, pulse, glow, shift — each visually distinct
8 bar styles	classic, block, shade, pipe, dot, square, star, braille
Lines changed	Shows +42 -7 in green/red — lines added and removed this session, read from stdin
Cumulative cost	Opt-in widget showing total API-equivalent cost across all sessions (cached, 5-min refresh)
Widget priorities	Every widget has a priority number — reorder them with --priority model=5,cost=15
Focus timer	Built-in focus timer — --focus start 25 shows countdown in the status bar
Auto-updates	Notifies when a new version of claude-pulse or Claude Code is available
Staleness indicator	Shows data age when cached data is old
Zero API calls	Reads rate limits directly from Claude Code's stdin (v2.1.80+) — no OAuth, no rate limiting

Quick Start

Plugin marketplace (recommended)

/plugin marketplace add NoobyGains/claude-pulse
/plugin install claude-pulse

Then run /pulse to configure. Restart Claude Code.

One-liner install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.ps1 | iex

Manual install

git clone https://github.com/NoobyGains/claude-pulse.git ~/.claude-pulse
python3 ~/.claude-pulse/claude_status.py --install

Restart Claude Code. That's it.

Enable the live heartbeat (optional)

The heartbeat shows a tool counter and elapsed time, updated on every tool call:

python3 ~/.claude-pulse/claude_status.py --install-hooks

Restart Claude Code for hooks to take effect.

Configuration

Use /pulse in Claude Code for an interactive setup wizard, or configure directly: