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.

# Windows — double-click setup.exe, or from a terminal:
setup.exe

# Linux
./setup

Debian/Ubuntu (.deb)

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

Installs binaries to /usr/bin/ and sets up autostart for the widget.

Linux (manual)

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:

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"
  }
}

Uninstall

Windows / Linux (setup tool)

# 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

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

# 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