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

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