claude-statusline

Monitor your Claude API usage — as a CLI statusline on headless servers or a system tray widget on desktop machines.

Both components share the same session key and fetcher logic. Install one or both depending on your setup.

Components

CLI Statusline (Node.js)

A headless-friendly status bar for Claude Code. Shows context window utilization and token usage as text progress bars, piped into the Claude Code statusline slot.

Context ▓▓▓▓░░░░░░ 40% | Token ▓▓░░░░░░░░ 19% 78M

Usage Fetcher (Node.js)

Standalone cron job that fetches token usage from the Claude API and writes a JSON cache file. The CLI statusline reads this cache. Runs independently — no browser or GUI needed.

Desktop Widget (Python)

Cross-platform system tray icon that shows the 5-hour usage window as a circular progress bar overlaid on a Claude starburst logo. Color shifts from green through amber to red as usage increases. Right-click menu shows detailed usage stats, reset timers, and configuration.

Topology

                          claude.ai API
                               |
                  ┌────────────┴────────────┐
                  |                         |
            fetch-usage.js           claude_usage_widget/
            (cron, Node.js)            fetcher.py thread
                  |                    (Python, urllib)
                  |                         |
                  └────────┬────────────────┘
                           v
                  /tmp/claude_usage.json
                     (shared cache)
                  ┌────────┴────────────────┐
                  |                         |
            statusline.js           claude_usage_widget/
            (Claude Code)              app.py (pystray)
                  |                         |
                  v                         v
          Claude Code               System tray icon
            status bar              + right-click menu

  Shared: ~/.config/claude-statusline/session-key
          /tmp/claude_usage.json

Only one fetcher needs to run. Either fetch-usage.js (via cron) or the widget's built-in fetcher thread writes to the shared cache at /tmp/claude_usage.json. Both consumers read from it:

• CLI statusline reads the cache on every Claude Code render cycle
• Desktop widget reads the cache on startup for instant display, then either fetches itself (writing back to cache) or detects that the cache is already fresh (from cron) and skips the API call

If both fetchers happen to run, they write the same format — last writer wins, no conflicts.

Installation

Run the installer and follow the wizard:

Linux / macOS:

bash install.sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1

The wizard will:

1. Ask which components to install (CLI statusline, desktop widget, or both)
2. Guide you through session key setup
3. Configure autostart (widget) or cron (CLI fetcher) as applicable
4. Set up the Claude Code statusline integration

Prerequisites

Component	Requires
CLI Statusline + Fetcher	Node.js 18+
Desktop Widget	Python 3.9+, pip
Desktop Widget (Linux)	python3-gi, gir1.2-ayatanaappindicator3-0.1 (installed by wizard)

Session Key

Both components authenticate via a session cookie from claude.ai:

1. Log into claude.ai in any browser
2. Open DevTools → Application → Cookies → claude.ai
3. Copy the value of the sessionKey cookie (starts with sk-ant-)
4. The installer will prompt you to enter it, or set it manually:

echo "sk-ant-..." > ~/.config/claude-statusline/session-key
chmod 600 ~/.config/claude-statusline/session-key

Alternatively, set the CLAUDE_SESSION_KEY environment variable.

Configuration

CLI Statusline

Environment variables:

Variable	Default	Description
CLAUDE_USAGE_CACHE	/tmp/claude_usage.json	Cache file path
CLAUDE_USAGE_MAX_AGE	900	Max cache age in seconds
CLAUDE_SESSION_KEY	—	Session key (alternative to config file)
CLAUDE_STATUSLINE_CONFIG	~/.config/claude-statusline	Config directory
CLAUDE_ORG_ID	—	Organization ID (auto-discovered)

Desktop Widget

Right-click the tray icon to access:

• Usage stats — 5-hour and 7-day utilization with reset timers
• Refresh Now — trigger an immediate fetch
• Refresh Interval — 1 / 5 / 15 / 30 minutes
• Session Key... — update the session key via dialog

Widget settings are stored in ~/.config/claude-statusline/widget-config.json.

Icon Color Scale

The tray icon arc color indicates usage severity at 10% increments:

Range	Color
0–10%	Green
10–20%	Dark green
20–30%	Light green
30–40%	Lime
40–50%	Yellow
50–60%	Amber
60–70%	Dark amber
70–80%	Orange
80–90%	Deep orange
90–100%	Red

Project Structure

claude-statusline/
├── statusline.js                  # CLI status bar (reads stdin + cache)
├── fetch-usage.js                 # Cron-based usage fetcher (writes cache)
├── install.sh                     # Linux/macOS installer wrapper
├── install.ps1                    # Windows installer wrapper
├── install_wizard.py              # Cross-platform installer wizard
├── package.json
├── requirements.txt               # Python deps (widget only)
├── claude_usage_widget/
│   ├── __init__.py
│   ├── __main__.py                # Entry point: python -m claude_usage_widget
│   ├── app.py                     # Tray icon orchestrator
│   ├── config.py                  # Shared config (~/.config/claude-statusline/)
│   ├── fetcher.py                 # Python port of fetch-usage.js (urllib)
│   ├── menu.py                    # Right-click menu builder
│   └── renderer.py                # Starburst logo + arc icon renderer
└── README.md

License

MIT