claude-statusline/README.md

claude-statusline

Monitor your Claude API usage — as a CLI statusline or a system tray widget

---

Overview

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

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

graph TD
  API["claude.ai API"]
  FetchJS["fetch-usage.js<br/>(cron / Node.js)"]
  FetchPy["fetcher.py thread<br/>(Python / urllib)"]
  Cache["/tmp/claude_usage.json<br/>(shared cache)"]
  SL["statusline.js<br/>(Claude Code)"]
  Widget["app.py<br/>(pystray tray icon)"]
  CC["Claude Code status bar"]
  Tray["System tray icon<br/>+ right-click menu"]
  SK["~/.config/claude-statusline/session-key"]

  API --> FetchJS
  API --> FetchPy
  FetchJS --> Cache
  FetchPy --> Cache
  Cache --> SL
  Cache --> Widget
  SL --> CC
  Widget --> Tray
  SK -.->|auth| FetchJS
  SK -.->|auth| FetchPy

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

Quick Install (from release)

Download the latest archive from the Releases page for your platform:

Platform	Download	Install
Linux	.tar.gz source archive	Extract, then bash install.sh
macOS	.tar.gz source archive	Extract, then bash install.sh
Windows	.zip source archive	Extract, then run install.ps1 (see Windows Quick Start below)

Planned: Native installers (.deb, .msi) are on the roadmap. For now, releases contain source archives.

Developer Install (from source)

Clone the repository and run the installer wizard:

Linux / macOS:

git clone https://git.davoryn.de/calic/claude-statusline.git
cd claude-statusline
bash install.sh

Windows (PowerShell):

git clone https://git.davoryn.de/calic/claude-statusline.git
cd claude-statusline
powershell -ExecutionPolicy Bypass -File install.ps1

What the wizard does

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

Windows Quick Start

If you're new to the command line, follow these steps:

1. Go to the Releases page and download the latest .zip file
2. Extract the zip to any folder (e.g. C:\Users\YourName\claude-statusline)
3. Open the extracted folder in File Explorer
4. Right-click install.ps1 and select Run with PowerShell
   • If you see a security prompt, choose Run anyway or Open
   • Alternatively, open PowerShell manually and run:

     powershell -ExecutionPolicy Bypass -File install.ps1
     

5. The wizard will walk you through component selection and session key setup
6. To find your session key, see Session Key below

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.

sequenceDiagram
  participant User
  participant Browser
  participant Installer
  participant Config

  User->>Browser: Log into claude.ai
  User->>Browser: DevTools → Cookies → sessionKey
  User->>Installer: Paste session key when prompted
  Installer->>Config: ~/.config/claude-statusline/session-key

Step by step:

1. Log into claude.ai in any browser
2. Open DevTools (press F12), go to Application → Cookies → https://claude.ai
3. Copy the value of the sessionKey cookie (it 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

Releases

Tagged releases are published on Gitea following semver (v0.2.0, v0.3.0, etc.). Each release includes per-OS source archives.

Planned future additions:

• .deb package for Debian/Ubuntu
• .msi / .exe installer for Windows
• Homebrew tap for macOS

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