Howl: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Howl — a Go statusline HUD for Claude Code. Reads JSON from stdin (piped every ~300ms), computes 5 derived metrics (context%, cache efficiency, API wait ratio, cost/min, tokens/sec) with 12 feature toggles, and outputs ANSI-formatted lines. Zero external dependencies (stdlib only), CGO_ENABLED=0, ~10ms cold start.

Module: github.com/ai-screams/howl

Commands

make build     # CGO_ENABLED=0 go build → build/howl
make install   # build + copy to ~/.claude/hud/howl
make unit-test # go test ./... -v -cover -coverprofile=coverage.out
make test      # smoke test: pipes sample JSON into built binary
make lint      # golangci-lint run
make fmt       # go fmt ./...
make fmt-docs  # prettier on *.md *.yaml *.yml
make check     # fmt + fmt-docs + lint + unit-test
make setup     # configure .githooks + install prettier

Run a single test:

go test ./internal -run TestComputeMetrics -v
go test ./cmd/howl -run TestVersionFlag -v

Architecture

Data Pipeline (main.go)

stdin JSON → json.Decode(StdinData) → LoadConfig → ComputeMetrics → GetGitInfo → GetUsage → ParseTranscript → GetAccountInfo → Render → stdout (ANSI lines, spaces → NBSP)

Every function after ComputeMetrics is optional — returns nil on failure, and Render gracefully omits that section. This is the core design principle: graceful degradation everywhere.

internal/ Package — Single Flat Package

All business logic lives in internal/ with no sub-packages. The dependency graph between files:

• types.go — StdinData struct matching Claude Code's JSON schema, ModelTier classification
• metrics.go — Metrics struct + ComputeMetrics(): context%, cache efficiency, API wait ratio, cost/min, tokens/sec
• constants.go — Default threshold values (danger 85%, warning 70%, moderate 50%, session cost $5/$1, cache 80/50%, API wait 60/35%, speed 60/30 tok/s, cost velocity $0.50/$0.10/min, quota 10/25/50/75%). All configurable via config.go Thresholds
• config.go — Config + FeatureToggles + Thresholds (17 configurable color/behavior values) + 4 presets (full/minimal/developer/cost-focused). LoadConfig() reads ~/.claude/hud/config.json with 4KB size guard. Features merge via mergeFeatures(base, override) — override can only enable, not disable. Thresholds merge via mergeThresholds(base, override) — only positive values override, validated via 3-step clamping
• render.go — Render() dispatches to renderNormalMode (2-4 lines) or renderDangerMode (2 dense lines) at configurable context threshold (default 85%). Line 2 supports priority ordering (max 5 metrics)
• git.go — GetGitInfo(): branch + dirty via subprocess with 1s timeout
• usage.go — GetUsage(): OAuth quota from api.anthropic.com/api/oauth/usage, 60s session-scoped cache in /tmp/howl-{sessionID}/. Token from macOS Keychain via /usr/bin/security
• transcript.go — ParseTranscript(): tail-reads last 64KB/100 lines of JSONL, extracts top-5 tools + running agents
• account.go — GetAccountInfo(): reads ~/.claude.json for email display