claude-statusline/README.md

# 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
bash install.sh
```

**Windows (PowerShell):**
```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](https://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:

```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 |

## 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