waybar-claude-code: Instructions file for Claude Code

waybar-claude-code

Waybar module displaying Claude Code usage statistics. Zero external dependencies, single binary output.

Architecture

Single execution model: Module runs once per invocation, outputs JSON, exits. Waybar handles polling via interval config.

Why one-shot execution:

• Simpler process lifecycle (no ticker management)
• Waybar already provides interval mechanism
• Lower memory footprint
• Easier debugging

Waybar JSON Protocol:

Custom modules with "return-type": "json" expect single-line JSON on stdout:

{"text": "display", "tooltip": "hover text", "class": "css-class", "percentage": 50}

Protocol rules:

• Single line output (no pretty printing)
• stdout for JSON only
• stderr for errors/logs
• Exit immediately after output

Project Structure

Core Go entrypoint lives in cmd/waybar-claude-code, while reusable logic is grouped under:

• internal/ccusage - Claude Code usage API client (API calls, caching, timeout handling)
• internal/config - Environment variable parsing
• internal/format - Tooltip rendering helpers with business rules
• pkg/waybar - Shared Waybar JSON protocol (reusable across modules)

Assets for docs and demos live in assets/, ready-to-copy Waybar + CSS samples in examples/. Keep binaries out of Git; waybar-claude-code at root is compiled output only.

Development Workflow

Build, test, run:

make build                  # Produces static binary with version metadata
make install                # Drops binary into ~/.config/waybar/modules/
make run RUN_INTERVAL=15    # Local debugging with 15s refresh
make fmt                    # Runs go fmt
make lint                   # Runs go vet + staticcheck
make test                   # Runs go test -race -cover ./...

Run make fmt, make lint, make test before any PR.

Build flags:

• CGO_ENABLED=0 - static binary
• -ldflags="-s -w" - strip debug symbols
• -X main.version - embed version from git

File locations for testing: