claude-statusline/README.md

claude-statusline

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

---

Overview

Three static binaries built from one Go codebase. No runtime dependencies — no Node.js, Python, or system packages needed.

CLI Statusline

Headless status bar for Claude Code. Shows context window utilization and token usage as text progress bars.

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

Usage Fetcher

Standalone binary for cron. Fetches token usage from the Claude API and writes a shared JSON cache.

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. Right-click menu shows detailed stats and configuration.

Topology

claude.ai API
     │
     ├──► claude-fetcher (cron)  ──► /tmp/claude_usage.json ──► claude-statusline (Claude Code)
     │                                       │
     └──► claude-widget (built-in fetcher) ──┘──► System tray icon

Only one fetcher needs to run. The widget has a built-in fetcher; the standalone claude-fetcher is for headless/cron setups. Both write the same cache format.

Installation

Debian/Ubuntu (.deb)

sudo dpkg -i claude-statusline_0.3.0_amd64.deb

Installs all three binaries to /usr/bin/, sets up autostart for the widget, and adds a cron job for the fetcher.

Linux (tar.gz)

tar xzf claude-statusline_0.3.0_linux_amd64.tar.gz
sudo cp claude-statusline-0.3.0/claude-{statusline,fetcher,widget} /usr/local/bin/

Windows

Extract the .zip and place the .exe files anywhere on your PATH.

Session Key Setup

After installing, paste your claude.ai session key:

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
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):

{
  "statusLine": {
    "type": "command",
    "command": "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

# All binaries
go build ./cmd/statusline && go build ./cmd/fetcher && go build ./cmd/widget

# 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 claude-fetcher.exe ./cmd/fetcher

# 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)
  fetcher/main.go        # Standalone cron fetcher (writes cache)
  widget/main.go         # Desktop tray widget entry point
internal/
  config/config.go       # Shared config (session key, org ID, intervals)
  fetcher/fetcher.go     # HTTP fetch logic (shared between widget + standalone)
  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, cron, install scripts

License

MIT