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
```mermaid
graph TD
API["claude.ai API"]
FetchJS["fetch-usage.js
(cron / Node.js)"]
FetchPy["fetcher.py thread
(Python / urllib)"]
Cache["/tmp/claude_usage.json
(shared cache)"]
SL["statusline.js
(Claude Code)"]
Widget["app.py
(pystray tray icon)"]
CC["Claude Code status bar"]
Tray["System tray icon
+ 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](https://git.davoryn.de/calic/claude-statusline/releases) 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](#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:**
```bash
git clone https://git.davoryn.de/calic/claude-statusline.git
cd claude-statusline
bash install.sh
```
**Windows (PowerShell):**
```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](https://git.davoryn.de/calic/claude-statusline/releases) 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
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](#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.
```mermaid
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](https://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:
```bash
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](https://git.davoryn.de/calic/claude-statusline/releases) 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