"Your AI screams — Howl listens."

A blazing-fast, feature-rich statusline HUD for Claude Code written in Go. Provides real-time visibility into your AI coding session with intelligent metrics, usage tracking, and adaptive layouts.

Real-time statusline HUD showing 1M context session with 13 intelligent metrics

• Features
• Installation
• Updating
• Uninstallation
• Usage
• Architecture
• Performance
• Development
• Configuration
  • Custom Thresholds
• Troubleshooting
• Why Howl?
• Roadmap
• Contributing
• License
• Credits

• Cache Efficiency — Track prompt cache utilization (80%+ = excellent)
• API Wait Ratio — See how much time spent waiting for AI responses
• Response Speed — Real-time tokens/second output rate
• Cost Velocity — Monitor spending rate ($/minute)

• Model Tier Badge — Color-coded Opus (gold) / Sonnet (cyan) / Haiku (green)
• Context Health Bar — Visual 10-char bar with 4-tier gradient
• Token Absolutes — See exact usage (210K/1M) with adaptive K/M formatting
• Usage Quota — Live 5h/7d limits with reset countdowns

• Git Integration — Branch name + dirty status (main*)
• Code Changes — Track lines added/removed with color coding
• Tool Usage — Top 5 most-used tools (Read, Bash, Edit...)
• Active Agents — See running subagents in real-time
• Vim Mode — N/I/V indicators for modal editing

• 17 Configurable Values — Control when every color changes and when danger mode activates
• Per-Group Tuning — Context, cost, cache, speed, API wait, cost velocity, quota
• Interactive Setup — Use /howl:threshold to adjust values conversationally
• Safe Defaults — Invalid values auto-corrected, zero values ignored

• Normal Mode (< 85% context, configurable) — 2-4 line display (lines added as features activate)
• Danger Mode (85%+ context, configurable) — Dense 2-line view with token breakdown and hourly cost
• Smart Grouping — Logical organization of related metrics

Choose your preferred installation method:

Current Status: Available for private repository access only. Will be available on the official Claude Marketplace after public release.

/plugin marketplace add ai-screams/howl
/plugin install howl@ai-screams-howl
/howl:setup

The /howl:setup skill automatically:

• Downloads the correct binary for your OS/architecture
• Installs to ~/.claude/hud/howl
• Configures ~/.claude/settings.json
• Backs up existing settings

After installation, use /howl:configure to choose a preset, /howl:customize for fine-grained metric toggles and priority ordering, or /howl:threshold to tune color breakpoints and danger mode trigger.

Once Howl is published to the official Claude Plugin Directory:

/plugin install howl@claude-plugin-directory

Or search for "howl" in /plugin > Discover.

Download the latest binary from GitHub Releases:

mkdir -p ~/.claude/hud

# macOS (Apple Silicon)
curl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_darwin_arm64 -o ~/.claude/hud/howl

# macOS (Intel)
curl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_darwin_amd64 -o ~/.claude/hud/howl

# Linux (x86_64)
curl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_linux_amd64 -o ~/.claude/hud/howl

# Linux (ARM64)
curl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_linux_arm64 -o ~/.claude/hud/howl

chmod +x ~/.claude/hud/howl

Then add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "/Users/YOUR_USERNAME/.claude/hud/howl"
  }
}

Verify: ~/.claude/hud/howl --version

Prerequisites: Go 1.24+, Claude Code CLI

git clone https://github.com/ai-screams/howl.git
cd Howl
make install
# Binary installed to ~/.claude/hud/howl

The Makefile automatically configures your settings.json.

Restart Claude Code to activate the statusline. The HUD will appear at the bottom of your terminal.

/howl:setup

Re-running the setup skill downloads the latest binary and replaces the existing one. Your configuration (~/.claude/hud/config.json) is preserved.

Re-download the latest binary:

curl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') \
  -o ~/.claude/hud/howl && chmod +x ~/.claude/hud/howl

cd howl && git pull && make install

No restart needed — changes apply on the next refresh (~300ms).

/plugin uninstall howl@ai-screams-howl

This removes the plugin but keeps the binary. To remove everything:

/plugin uninstall howl@ai-screams-howl
rm ~/.claude/hud/howl

Then remove the statusLine field from ~/.claude/settings.json.

1. Remove binary: rm ~/.claude/hud/howl
2. Remove statusLine field from ~/.claude/settings.json
3. Restart Claude Code

Howl runs automatically as a subprocess every ~300ms. No manual interaction needed.

Normal Mode (21% context, 1M):

🟢 Sonnet 4.5 1M | [email protected] | main | 15 tok/s | $24.5 | 29h15m
██░░░░░░░░  21% (210K/  1M) | ████████░░  78% (2h00m/5h) | █████████░  88% (3d21h/7d)
+328 -67 | Cache 99% (R:180K W:30K) | Wait 6% | $0.01/m | VIM:I | CC 1.0.18
Bash(2)

Danger Mode (100% context, 200K):

🟣 Opus 4.6 | 🔴 ██████████ 100% 0K left ~0m | ████████░░  72% (2h00m/5h)
main | +328 -67 | 15 tok/s | Cache 99% | Wait 6% | $0.01/m

Tip: All color thresholds above are defaults. You can customize every breakpoint via /howl:threshold or ~/.claude/hud/config.json. See Custom Thresholds below.

Note: The context window percentage shown by Howl reflects the raw used_percentage from Claude Code's stdin JSON. This does not account for the auto-compact buffer (~10-17% reserved internally by Claude Code). Actual free context before auto-compaction triggers may be lower than displayed. This is a Claude Code limitation — the auto-compact threshold is not exposed in the statusline JSON schema.

Claude Code (every ~300ms)
    │
    ├─ Pipes JSON to stdin
    │
    ▼
┌─────────────────────────────────────┐
│  Howl Binary (Go)                   │
│                                     │
│  1. Parse stdin JSON                │
│  2. Compute derived metrics         │
│  3. Fetch git status (1s timeout)   │
│  4. Get OAuth quota (60s cache)     │
│  5. Parse transcript (last 100 ln)  │
│  6. Render ANSI output              │
│  7. Output to stdout                │
└─────────────────────────────────────┘
    │
    ▼
Claude Code Statusline Display

howl/
├── cmd/
│   └── howl/
│       ├── main.go          # Entry point, orchestration
│       └── main_test.go     # Main package tests
├── internal/
│   ├── constants.go         # Threshold constants
│   ├── types.go             # StdinData structs, model classification
│   ├── types_test.go        # Types tests
│   ├── metrics.go           # Derived calculations
│   ├── metrics_test.go      # Metrics tests
│   ├── render.go            # ANSI output generation
│   ├── render_test.go       # Render tests
│   ├── config.go            # Configuration system
│   ├── config_test.go       # Config tests
│   ├── git.go               # Git subprocess calls
│   ├── git_test.go          # Git tests
│   ├── usage.go             # OAuth quota API
│   ├── usage_test.go        # Usage tests
│   ├── account.go           # Account tier detection
│   ├── account_test.go      # Account tests
│   ├── transcript.go        # JSONL parsing
│   ├── transcript_test.go   # Transcript tests
│   ├── integration_test.go  # Integration tests
│   └── testdata/            # JSONL test fixtures
├── docs/                    # Design & research documents
├── skills/
│   ├── setup/SKILL.md       # /howl:setup (installation)
│   ├── configure/SKILL.md   # /howl:configure (preset selection)
│   ├── customize/SKILL.md   # /howl:customize (metric toggles)
│   └── threshold/SKILL.md   # /howl:threshold (color thresholds)
├── .claude-plugin/          # Claude Code plugin metadata
├── Makefile                 # Build automation
└── go.mod                   # Go module definition

• constants.go — Default threshold constants (danger %, cache %, speed, cost, quotas, timeouts)
• config.go — Configuration system with presets, feature toggles, and 17 customizable thresholds
• types.go — StdinData schema matching Claude Code's JSON output, model tier classification
• metrics.go — Cache efficiency, API ratio, cost velocity, response speed calculations
• render.go — ANSI color codes, adaptive layouts (normal 2-4 lines / danger 2 lines), threshold-driven colors
• git.go — Branch detection with graceful 1s timeout
• usage.go — Anthropic OAuth API client with session-scoped 60s caching
• transcript.go — Tool usage extraction from conversation history (last ~100 lines)

Test Environment:

• Platform: macOS (Apple Silicon)
• Go: 1.24.13
• Runs: 20 iterations (minimal), 10 iterations (full)

*First OAuth call (uncached)

Optimizations:

• Compiled Go binary (no interpreter startup)
• Session-scoped caching for external API calls
• Tail-only transcript parsing (vs full file scan)
• 1-second timeout on git operations
• Zero external dependencies (stdlib only)

make build         # Compile to build/howl
make install       # Copy to ~/.claude/hud/howl
make clean         # Remove build artifacts
make test          # Smoke test with sample JSON input
make unit-test     # Run unit tests
make release-dry   # Test GoReleaser locally (snapshot)
make release-check # Validate .goreleaser.yaml

1. Add field to Metrics struct in internal/metrics.go
2. Implement calculation function
3. Call in ComputeMetrics()
4. Add render function in internal/render.go
5. Integrate into layout (normal/danger modes)

Example:

// metrics.go
type Metrics struct {
    // ...
    NewMetric *int
}

func calcNewMetric(d *StdinData) *int {
    // calculation logic
}

// render.go
func renderNewMetric(val int) string {
    return fmt.Sprintf("%s%d%s", color, val, Reset)
}

All 17 color breakpoints and the danger mode trigger are configurable via ~/.claude/hud/config.json:

{
  "preset": "full",
  "thresholds": {
    "context_danger": 92,
    "context_warning": 80,
    "session_cost_high": 20.0,
    "speed_fast": 100,
    "quota_high": 90
  }
}

Only specified values override defaults — omitted fields keep their default values.

Interactive setup: Run /howl:threshold in Claude Code to adjust values conversationally — choose a group, set values, and see before/after comparisons.

Validation: Invalid values are auto-corrected (inverted pairs clamped, out-of-range values bounded). Zero or negative values are ignored. Malformed JSON falls back to all defaults silently.

Changes apply on the next refresh (~300ms) — no restart needed.

Howl automatically reads OAuth tokens from macOS Keychain:

• Service: Claude Code-credentials
• Extracted field: claudeAiOauth.accessToken

No manual configuration needed if Claude Code is authenticated.

• Usage quota cache: $TMPDIR/howl-{session_id}/usage.json (60s TTL)
• Session-scoped: Each Claude Code session has isolated cache via session_id

• OAuth API unavailable or credentials expired
• Check: security find-generic-password -s "Claude Code-credentials" -w
• Fallback: Quota display is optional, other metrics still work

• Not a git repository
• Git timeout (1s) exceeded
• Solution: Initialize git or ignore (graceful degradation)

• Transcript file not accessible
• Session just started (no tools used yet)
• Solution: Wait for tool usage or check transcript path

• Large transcript file (>10MB)
• Network latency for OAuth API
• Solution: Transcript parses last 100 lines only, quota cached for 60s

Howl was created to solve specific pain points with existing Claude Code statusline tools.

• Session isolation — Cache per session_id, preventing cross-session bugs
• OAuth headers — Correct anthropic-beta header included for API access
• Rich metrics — 13 distinct indicators across 2-4 display lines
• Go performance — ~10ms cold start, 5.6MB binary, zero dependencies
• 1M context ready — Adaptive K/M formatting for large windows

• Configuration file support (~/.claude/hud/config.json) — Available in v1.3.0+
• Auto-sync plugin.json version in release pipeline — Available in v1.4.0+
• Custom thresholds — 17 configurable color breakpoints and danger mode trigger — Available in v1.5.0+
• Custom color schemes
• Plugin system for custom metrics
• Windows support

This is a personal tool for the AiScream project. Feedback and bug reports welcome!

MIT License — see LICENSE file for details.

For release history and detailed changes, see CHANGELOG.md.

Project: ai-screams/howl
Author: pignuante
Inspired by: claude-hud by Jarrod Watts

Built with ❤️ and Claude Code.