Claude Pulse

Monitor Claude Code usage, sessions, subagents and token consumption directly from your VS Code status bar.

Claude Pulse gives you real-time visibility into your Claude Code activity — usage percentages across rate-limit windows, session reset countdowns, token breakdowns by model, and weekly usage trends — plus a map of every Claude session on your machine and the subagents it spawned, with a button to terminate a session that has run away. All without leaving your editor.

Features

Status Bar

• Live usage percentage (max across 5-hour and 7-day windows)
• Session reset countdown timer (from API or estimated)
• Current model and reasoning effort level (e.g. Opus 5 · xhigh), each shown/hidden independently
• Model-specific weekly usage once it registers (e.g. Fable 2% 4d 5h) — a sub-cap within the weekly limit
• Optional approximate prompt-cache countdown (e.g. ~42m), so you know whether coming back now is cheap
• Optional message count and session count display
• Five-tier color-coded usage: blue (<25%), green (25-49%), amber (50-69%), orange (70-89%), red (90%+)

Interactive Dashboard

Open with the Claude Pulse: Show Dashboard command to see:

• Usage bars — Every rate-limit window the API reports: current session (5h), weekly (all models), model-specific weekly windows such as This Week (Fable), and extra usage
• Prompt cache — Roughly how long your prompt cache stays warm, estimated from your last request
• Loops — Every /loop your sessions have scheduled, grouped by session: the prompt, its schedule (every 5 min, weekdays at 08:57, or self-paced), status (active, cancelled, completed, expired, ended), how many times it has run, when it last ran, when it runs next, and when it expires. Scanned only when you press Show loops / Refresh loops. Each active loop has Run now (run its prompt ahead of schedule) and Cancel buttons; both are confirmed first and are typed into the session's terminal, or copied to the clipboard when the session is not in one of this window's terminals
• Session info — Active session PID, working directory, duration, and reset time
• Weekly summary — Total tokens, messages, sessions, and tool calls for the current week
• Sonnet breakdown — Sonnet token usage and percentage of total
• Lifetime stats — Total tokens, favorite model, total sessions and messages, first session date, longest session, active-day streaks, and most active day
• Model breakdown — Token usage table by model (input, output, cache read, cache create)
• Hourly activity chart — Visual bar chart of activity distribution by hour
• Agents — The subagents the current session spawned, costliest first, with task, type, model, turns, duration and tokens
• Agent graph — A tab per agent type showing the sessions that ran it, plus a Sessions tab with each session's full subagent tree. Every run shows its type, model, turns, cost and status (running, completed, stopped, never finished), and every session carries a button to terminate it

Agents & Session Control

• See every session on the machine — not just this window's — with the subagents each one spawned, including agents spawned by other agents
• Browse by agent type — one tab per type (general-purpose, Explore, …) to compare its runs across sessions, or the Sessions tab for each session's full tree
• Lifecycle status per run — running, completed, stopped by you, or never finished — read from the transcripts, with running agents always listed first
• Terminate a session — from its node in the graph, or with Claude Pulse: Terminate a Claude Session. Every termination is confirmed first and sends SIGTERM so Claude Code saves its transcript on the way out; SIGKILL is offered only if that is ignored
• Stop a running subagent — subagents run inside their session's process, so this terminates that session, and the confirmation says so and names the other agents that go with it

Real-Time Monitoring

• File watching on ~/.claude/ for stats and session changes
• Per-window session matching — each VS Code window follows the Claude session for its own workspace folder, so running Claude in several projects at once never mixes them up
• PID liveness detection for active session tracking
• Notifications on session start, session end, and reset timer completion
• Optional OS-level system notifications (via node-notifier)

Usage API Integration

• Fetches live usage data from the Anthropic API using your existing OAuth credentials
• Reads credentials from macOS Keychain or ~/.claude/.credentials.json
• Retry logic with exponential backoff and rate-limit handling
• Configurable refresh interval (minimum 60 seconds), plus an opportunistic refresh right after Claude finishes a task so the percentage is current when you look at it

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for Claude Pulse
4. Click Install

Or install from the command line:

code --install-extension AlirezaSoltaniJazi.claude-pulse-monitor

Requirements

• VS Code 1.85.0 or later
• Claude Code CLI installed and logged in (for stats data in ~/.claude/)
• OAuth login via Claude Code CLI (for live API usage data — optional but recommended)

Configuration

All settings are under claudePulse.* in VS Code Settings.

Commands

How It Works

Claude Pulse reads data from two sources:

1. Local files (~/.claude/) — Claude Code writes session files, stats cache, and JSONL session logs to this directory. Claude Pulse watches these files for changes and aggregates weekly usage from JSONL logs.

2. Anthropic API (api.anthropic.com/api/oauth/usage) — When OAuth credentials are available, Claude Pulse fetches live usage percentages and reset times. Credentials are read from the macOS Keychain or ~/.claude/.credentials.json — the extension never stores credentials itself.

Subagent transcripts are by far the largest files Claude Code writes, so the Agents and Agent Graph sections read them only while the dashboard is open, and each finished agent is read once and then cached. Loops live only in the memory of the Claude session that scheduled them — nothing about them is written to disk — so the Loops section reconstructs them from the CronCreate, CronDelete and ScheduleWakeup calls in each session's transcript. Because that means reading whole transcripts, it runs only when you press its button, never on the poll. The only action Claude Pulse ever takes beyond reading is terminating a session, and only when you confirm it.

Privacy & Security

• No telemetry: Claude Pulse does not collect, store, or transmit any analytics or telemetry data
• Local data only: Stats and session data are read from your local ~/.claude/ directory (read-only)
• Process control is opt-in per action: the one thing Claude Pulse does beyond reading files is terminate a Claude session when you ask it to. Every termination is confirmed in a modal first, only a PID that still matches a known session's id is ever signalled, and SIGTERM is always tried before SIGKILL is offered
• Secure credentials: OAuth tokens are read from the OS Keychain (macOS) or a local file — never stored by the extension
• HTTPS only: All API communication uses HTTPS
• No eval: The dashboard webview runs only first-party JavaScript — no eval() or dynamic code execution
• Open source: Full source code available at github.com/AlirezaSoltaniJazi/claude-pulse

System Notifications Setup (macOS)

Claude Pulse can send OS-level desktop notifications (e.g., when Claude finishes a task). To enable:

1. In VS Code Settings, enable:
   • Claude Pulse > Notifications: Enabled → checked
   • Claude Pulse > Notifications: Use System Notifications → checked
2. The first notification will prompt macOS to register terminal-notifier
3. Go to System Settings → Notifications → terminal-notifier and make sure:
   • Allow Notifications is turned on
   • Alert style is set to Banners or Alerts (not "None")
4. Make sure Focus / Do Not Disturb mode is off, or allow terminal-notifier through Focus settings

After setup, you'll receive macOS notification banners for:

• Task completion (Claude finished and is waiting for input)
• Session start/end
• Session reset timer complete

Known Limitations

• OAuth credential reading uses the macOS Keychain, with a file-based fallback (~/.claude/.credentials.json) on Linux and Windows.
• The extension reads stats written by Claude Code CLI — if the CLI changes its file format, stats parsing may need updates.
• Usage API data depends on having a valid OAuth session with Claude Code.
• A single subagent cannot be stopped from outside Claude Code. Subagents share their session's process, so the graph's Stop button terminates that whole session — and says so before it does.
• Subagent status is inferred from the transcripts, not reported. A completed agent is proven by the terminal stop_reason on its last turn and a user-cancelled one by its own metadata, but an agent that was abandoned mid-work is recognised only once it has gone quiet, so it reads as running until then.

Contributing

Contributions are welcome! Please see the repository for details.

# Clone and install
git clone https://github.com/AlirezaSoltaniJazi/claude-pulse.git
cd claude-pulse
npm install

# Development
npm run watch    # Build in watch mode
# Press F5 in VS Code to launch Extension Development Host
npm run dev      # or: build once + launch Extension Development Host directly (no F5 needed)

# Quality checks
npm run lint     # ESLint
npm run format:check  # Prettier
npm test         # Vitest (213 tests)
npm run build    # Production build

License

MIT

Claude Pulse is an independent, community-built extension. It is not officially affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" is a trademark of Anthropic.