claude-statusline/README.md

<h1 align="center">claude-statusline</h1>

<p align="center">
  Monitor your Claude API usage — as a CLI statusline or a system tray widget
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go&logoColor=white" alt="Go 1.21+" />
  <img src="https://img.shields.io/badge/Platform-Linux%20|%20Windows-informational" alt="Platform: Linux | Windows" />
  <img src="https://img.shields.io/badge/Dependencies-zero-brightgreen" alt="Zero dependencies" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
  <br />
  <a href="https://git.davoryn.de/calic/claude-statusline/releases"><img src="https://img.shields.io/badge/releases-Gitea-blue?logo=gitea&logoColor=white" alt="Releases" /></a>
</p>

---

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

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

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

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

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