claude-statusline
Monitor your Claude API usage — as a CLI statusline or a system tray widget
---
## Overview
Two static binaries built from one Go codebase. No runtime dependencies — no Node.js, Python, or system packages needed. A `setup` tool handles installation and uninstallation on both platforms.
### CLI Statusline
Headless status bar for Claude Code. Shows context window utilization and token usage as text progress bars.
```
Context ▓▓▓▓░░░░░░ 40% | Token ▓▓░░░░░░░░ 19% 78M
```
### Desktop Widget
System tray icon showing 5-hour usage as a circular progress bar on a Claude starburst logo. Color shifts from green through amber to red as usage increases. Has a built-in background fetcher that writes a shared JSON cache. Right-click menu shows detailed stats and configuration.
## Topology
```
claude.ai API
│
└──► claude-widget (background fetcher) ──► /tmp/claude_usage.json ──► claude-statusline (Claude Code)
│
└──► System tray icon
```
## Installation
### Windows / Linux (setup tool)
Extract the archive and run the setup tool. It copies binaries to the install directory, enables autostart for the widget, and configures Claude Code's statusline setting.
```bash
# Windows — double-click setup.exe, or from a terminal:
setup.exe
# Linux
./setup
```
### Debian/Ubuntu (.deb)
```bash
sudo dpkg -i claude-statusline_0.3.0_amd64.deb
```
Installs binaries to `/usr/bin/` and sets up autostart for the widget.
### Linux (manual)
```bash
tar xzf claude-statusline_0.3.0_linux_amd64.tar.gz
cp claude-statusline-0.3.0/claude-{statusline,widget} ~/.local/bin/
```
### Session Key Setup
After installing, paste your claude.ai session key:
```bash
mkdir -p ~/.config/claude-statusline
echo "sk-ant-..." > ~/.config/claude-statusline/session-key
chmod 600 ~/.config/claude-statusline/session-key
```
**To find your session key:**
1. Log into [claude.ai](https://claude.ai)
2. Open DevTools (`F12`) → **Application** → **Cookies** → `https://claude.ai`
3. Copy the `sessionKey` cookie value
Or set `CLAUDE_SESSION_KEY` as an environment variable.
### Claude Code Integration
Add to your Claude Code settings (`~/.claude/settings.json`):
```json
{
"statusLine": {
"type": "command",
"command": "claude-statusline"
}
}
```
## Uninstall
### Windows / Linux (setup tool)
```bash
# Windows
setup.exe --uninstall
# Linux
./setup --uninstall
```
Stops the widget, removes binaries and autostart entry, and cleans the `statusLine` setting from Claude Code. Optionally removes the config directory (interactive prompt, default: keep).
### Debian/Ubuntu
```bash
sudo dpkg -r claude-statusline
```
## Configuration
### 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 |
### Widget Menu
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...** — open session key file in editor
### Icon Color Scale
| 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 |
## Building from Source
```bash
# All binaries
go build ./cmd/statusline && go build ./cmd/widget && go build ./cmd/setup
# Cross-compile for Windows
GOOS=windows GOARCH=amd64 go build -ldflags "-H=windowsgui" -o claude-widget.exe ./cmd/widget
GOOS=windows GOARCH=amd64 go build -o claude-statusline.exe ./cmd/statusline
GOOS=windows GOARCH=amd64 go build -o setup.exe ./cmd/setup
# Build .deb
VERSION=0.3.0 nfpm package --config packaging/nfpm.yaml --packager deb
```
## Project Structure
```
cmd/
statusline/main.go # CLI statusline (reads stdin + cache)
widget/main.go # Desktop tray widget with built-in fetcher
setup/main.go # Cross-platform install/uninstall tool
internal/
config/config.go # Shared config (session key, org ID, intervals)
fetcher/fetcher.go # HTTP fetch logic (used by widget)
fetcher/cache.go # JSON cache read/write (/tmp/claude_usage.json)
renderer/renderer.go # Icon rendering: starburst + arc (fogleman/gg)
tray/tray.go # System tray setup + menu (fyne-io/systray)
packaging/
nfpm.yaml # .deb packaging config
linux/ # .desktop file, install scripts
```
## License
MIT