{
"markdown": "# Howl\n\n> _\"Your AI screams β Howl listens.\"_\n\nA blazing-fast, feature-rich statusline HUD for [Claude Code](https://code.claude.com) written in Go. Provides real-time visibility into your AI coding session with intelligent metrics, usage tracking, and adaptive layouts.\n\n[](https://go.dev)\n[](https://github.com/ai-screams/howl/releases)\n[](https://github.com/ai-screams/howl/releases)\n[](https://github.com/ai-screams/howl)\n[](LICENSE)\n[](https://github.com/ai-screams/howl/commits)\n[](https://github.com/ai-screams/howl/graphs/commit-activity)\n\n[](https://github.com/ai-screams/howl/actions)\n[]()\n[]()\n[](https://goreportcard.com/report/github.com/ai-screams/howl)\n[](https://pkg.go.dev/github.com/ai-screams/howl)\n[]()\n[]()\n[](https://conventionalcommits.org)\n\n[]()\n[]()\n[]()\n[](https://github.com/ai-screams/howl/releases)\n[](https://github.com/ai-screams/howl/releases)\n[](https://code.claude.com)\n[]()\n[](https://github.com/ai-screams/howl/issues)\n\n---\n\n\n\n_Real-time statusline HUD showing 1M context session with 17 intelligent metrics_\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Updating](#updating-)\n- [Uninstallation](#uninstallation)\n- [Usage](#usage)\n- [Architecture](#architecture)\n- [Performance](#performance)\n- [Development](#development)\n- [Configuration](#configuration)\n - [Custom Thresholds](#custom-thresholds)\n- [Troubleshooting](#troubleshooting)\n- [Why Howl?](#why-howl)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Credits](#credits)\n\n---\n\n## Features\n\n### Intelligent Metrics π\n\n- **Cache Efficiency** β Track prompt cache utilization (80%+ = excellent)\n- **API Wait Ratio** β See how much time spent waiting for AI responses\n- **Cost Velocity** β Monitor spending rate ($/minute)\n\n### Essential Status π―\n\n- **Model Tier Badge** β Color-coded Opus (gold) / Sonnet (cyan) / Haiku (green)\n- **Context Health Bar** β Visual 10-char bar with 4-tier gradient\n- **Token Absolutes** β See exact usage (210K/1M) with adaptive K/M formatting\n- **Usage Quota** β Live 5h/7d limits with reset countdowns (reads `rate_limits` from stdin; requires Claude.ai subscriber + CC 2.1.80+)\n\n### Workflow Awareness π§\n\n- **Git Integration** β Branch name + dirty status (`main*`)\n- **Code Changes** β Track lines added/removed with color coding\n- **Tool Usage** β Top 5 most-used tools (Read, Bash, Edit...)\n- **Active Agents** β See running subagents in real-time\n- **Vim Mode** β N/I/V indicators for modal editing\n\n### Custom Thresholds β‘\n\n- **15 Configurable Values** β Control when every color changes and when danger mode activates\n- **Per-Group Tuning** β Context, cost, cache, API wait, cost velocity, quota\n- **Interactive Setup** β Use `/howl:threshold` to adjust values conversationally\n- **Safe Defaults** β Invalid values auto-corrected, zero values ignored\n\n### Optional Feature Toggles (default off) π§\n\nEnable individually via `features` in `~/.claude/hud/config.json` or `/howl:customize`:\n\n- **output_tokens** β Current-response output token count (`Out:1K`) β truthful replacement for the removed tok/s metric; reads `current_usage.output_tokens` directly\n- **effort** β Shows current effort level (`E:high`)\n- **thinking** β Shows extended thinking indicator (`Think`)\n- **session_name** β Shows truncated session name\n- **pull_request** β Shows linked PR (`PR#1234 pending`)\n- **worktree** β Shows active git worktree (`wt:name`)\n\n### Adaptive Layouts π¨\n\n- **Normal Mode** (< 85% context, configurable) β 2-4 line display (lines added as features activate)\n- **Danger Mode** (85%+ context, configurable) β Dense 2-line view with token breakdown and hourly cost\n- **Smart Grouping** β Logical organization of related metrics\n- **Width-Aware Rendering** β Tool/agent line sizes to `COLUMNS` env var (clamped 40β240, fallback 80; requires CC 2.1.153+)\n\n---\n\n\n\n## Installation πΎ\n\nChoose your preferred installation method:\n\n### Method 1: Claude Code Plugin (Recommended) π\n\n**Current Status:** Available for private repository access only. Will be available on the official Claude Marketplace after public release.\n\n#### Via Self-hosted Marketplace\n\n```bash\n/plugin marketplace add ai-screams/howl\n/plugin install howl@ai-screams-howl\n/howl:setup\n```\n\nThe `/howl:setup` skill automatically:\n\n- Downloads the correct binary for your OS/architecture\n- Installs to `~/.claude/hud/howl`\n- Configures `~/.claude/settings.json`\n- Backs up existing settings\n\nAfter 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.\n\n#### Via Official Marketplace (Coming Soon)\n\nOnce Howl is published to the official Claude Plugin Directory:\n\n```bash\n/plugin install howl@claude-plugin-directory\n```\n\nOr search for \"howl\" in `/plugin > Discover`.\n\n---\n\n### Method 2: Direct Binary Download π¦\n\nDownload the latest binary from [GitHub Releases](https://github.com/ai-screams/howl/releases/latest):\n\n```bash\nmkdir -p ~/.claude/hud\n\n# macOS (Apple Silicon)\ncurl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_darwin_arm64 -o ~/.claude/hud/howl\n\n# macOS (Intel)\ncurl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_darwin_amd64 -o ~/.claude/hud/howl\n\n# Linux (x86_64)\ncurl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_linux_amd64 -o ~/.claude/hud/howl\n\n# Linux (ARM64)\ncurl -fsSL https://github.com/ai-screams/howl/releases/latest/download/howl_linux_arm64 -o ~/.claude/hud/howl\n\nchmod +x ~/.claude/hud/howl\n```\n\nThen add to `~/.claude/settings.json`:\n\n```json\n{\n \"statusLine\": {\n \"type\": \"command\",\n \"command\": \"/Users/YOUR_USERNAME/.claude/hud/howl\"\n }\n}\n```\n\nVerify: `~/.claude/hud/howl --version`\n\n---\n\n### Method 3: Build from Source π οΈ\n\nPrerequisites: Go 1.24+, Claude Code CLI\n\n```bash\ngit clone https://github.com/ai-screams/howl.git\ncd Howl\nmake install\n# Binary installed to ~/.claude/hud/howl\n```\n\nThe Makefile automatically configures your settings.json.\n\n---\n\n### Post-Installation β
\n\nRestart Claude Code to activate the statusline. The HUD will appear at the bottom of your terminal.\n\n---\n\n## Updating π\n\n### If installed via Plugin (automatic)\n\nThe binary keeps itself in sync with the plugin β no manual step needed:\n\n1. Claude Code auto-updates the **plugin** content from the marketplace (enable marketplace auto-update; third-party marketplaces are not auto-updated by default: `claude plugin marketplace update ai-screams-howl`).\n2. The plugin's `SessionStart` hook (`scripts/sync-binary.sh`) detects the new plugin version and re-downloads the matching **binary** in the background.\n\nIt is a no-op (no network) when already in sync, only updates an existing install, and never blocks session start. To force an immediate update, re-run `/howl:setup`. Your configuration (`~/.claude/hud/config.json`) is always preserved.\n\n### If installed via Direct Download\n\nRe-download the latest binary:\n\n```bash\ncurl -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/') \\\n -o ~/.claude/hud/howl && chmod +x ~/.claude/hud/howl\n```\n\n### If built from Source\n\n```bash\ncd howl && git pull && make install\n```\n\nNo restart needed β changes apply on the next refresh (~300ms).\n\n---\n\n\n\n## Uninstallation ποΈ\n\n### If installed via Plugin\n\n```bash\n/plugin uninstall howl@ai-screams-howl\n```\n\nThis removes the plugin but keeps the binary. To remove everything:\n\n```bash\n/plugin uninstall howl@ai-screams-howl\nrm ~/.claude/hud/howl\n```\n\nThen remove the `statusLine` field from `~/.claude/settings.json`.\n\n### If installed manually\n\n1. Remove binary: `rm ~/.claude/hud/howl`\n2. Remove `statusLine` field from `~/.claude/settings.json`\n3. Restart Claude Code\n\n---\n\n## Usage\n\nHowl runs automatically as a subprocess every ~300ms. No manual interaction needed.\n\n### Example Output\n\n**Normal Mode (21% context, 1M):**\n\n\n\n\nText output (for accessibility)
\n\n```\nπ’ Sonnet 4.5 1M | hanyul.ryu@gmail.com | main | Out:1K | $24.5 | 29h15m\nββββββββββ 21% (210K/ 1M) | ββββββββββ 78% (2h00m/5h) | ββββββββββ 88% (3d21h/7d)\n+328 -67 | Cache 99% (R:180K W:30K) | Wait 6% | $0.01/m | VIM:I | CC 1.0.18\nBash(2)\n```\n\n \n\n**Danger Mode (100% context, 200K):**\n\n\n\n\nText output (for accessibility)
\n\n```\nπ£ Opus 4.6 | π΄ ββββββββββ 100% 0K left ~0m | ββββββββββ 72% (2h00m/5h)\nmain | +328 -67 | Cache 99% | Wait 6% | $0.01/m\n```\n\n \n\n### Metrics Explained\n\n| Metric | Meaning | Color Coding |\n| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| **Cache 96%** | Prompt cache efficiency (% of input from cache) | Green (80%+), Yellow (50-80%), Red (<50%) |\n| **Wait 41%** | Time spent waiting for API responses | Green (<35%), Yellow (35-60%), Red (60%+) |\n| **$0.19/m** | API spending rate per minute | Green (<$0.10), Yellow ($0.10-0.50), Red ($0.50+) |\n| **Out:1K** | Output tokens for the current response | Static (no color coding; opt-in via `output_tokens` toggle) |\n| **78% (2h00m/5h)** | 5-hour quota: 78% remaining, resets in 2h | Gradient based on % remaining |\n| **88% (3d21h/7d)** | 7-day quota: 88% remaining, resets in 3d21h | Gradient based on % remaining |\n| **π₯ on quota bar** | Quota window is ahead of even pace β projected to be exhausted before it resets | Appended to the quota bar; no separate toggle (shows under existing `quota` feature) |\n\n> **Tip:** All color thresholds above are defaults. You can customize every breakpoint via `/howl:threshold` or `~/.claude/hud/config.json`. See [Custom Thresholds](#custom-thresholds) below.\n\n> **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.\n\n---\n\n## Architecture\n\n### Data Flow\n\n```\nClaude Code (every ~300ms)\n β\n ββ Pipes JSON to stdin (includes rate_limits for quota)\n β\n βΌ\nβββββββββββββββββββββββββββββββββββββββ\nβ Howl Binary (Go) β\nβ β\nβ 1. Parse stdin JSON β\nβ 2. Compute derived metrics β\nβ 3. Fetch git status (1s timeout) β\nβ 4. Convert rate_limits β quota β\nβ 5. Parse transcript (last 100 ln) β\nβ 6. Render ANSI output β\nβ 7. Output to stdout β\nβββββββββββββββββββββββββββββββββββββββ\n β\n βΌ\nClaude Code Statusline Display\n```\n\n### Project Structure\n\n```\nhowl/\nβββ cmd/\nβ βββ howl/\nβ βββ main.go # Entry point, orchestration\nβ βββ main_test.go # Main package tests\nβββ internal/\nβ βββ constants.go # Threshold constants\nβ βββ types.go # StdinData structs, model classification\nβ βββ types_test.go # Types tests\nβ βββ metrics.go # Derived calculations\nβ βββ metrics_test.go # Metrics tests\nβ βββ render.go # ANSI output generation\nβ βββ render_test.go # Render tests\nβ βββ config.go # Configuration system\nβ βββ config_test.go # Config tests\nβ βββ git.go # Git subprocess calls\nβ βββ git_test.go # Git tests\nβ βββ usage.go # rate_limits β quota converter (no I/O)\nβ βββ usage_test.go # Usage tests\nβ βββ account.go # Account tier detection\nβ βββ account_test.go # Account tests\nβ βββ transcript.go # JSONL parsing\nβ βββ transcript_test.go # Transcript tests\nβ βββ integration_test.go # Integration tests\nβ βββ testdata/ # JSONL test fixtures\nβββ docs/ # Design & research documents\nβββ skills/\nβ βββ setup/SKILL.md # /howl:setup (installation)\nβ βββ configure/SKILL.md # /howl:configure (preset selection)\nβ βββ customize/SKILL.md # /howl:customize (metric toggles)\nβ βββ threshold/SKILL.md # /howl:threshold (color thresholds)\nβββ hooks/\nβ βββ hooks.json # SessionStart hook: binary auto-update\nβββ scripts/\nβ βββ install.sh # Download binary + configure statusLine\nβ βββ sync-binary.sh # Keep binary in sync with plugin version\nβββ .claude-plugin/ # Claude Code plugin metadata (plugin.json, marketplace.json)\nβββ Makefile # Build automation\nβββ go.mod # Go module definition\n```\n\n### Key Modules\n\n- **constants.go** β Default threshold constants (danger %, cache %, cost, quotas, timeouts)\n- **config.go** β Configuration system with presets, feature toggles, and 15 customizable thresholds\n- **types.go** β StdinData schema matching Claude Code's JSON output, model tier classification\n- **metrics.go** β Cache efficiency, API ratio, cost velocity calculations\n- **render.go** β ANSI color codes, adaptive layouts (normal 2-4 lines / danger 2 lines), threshold-driven colors\n- **git.go** β Branch detection with graceful 1s timeout\n- **usage.go** β Pure `rate_limits` β quota converter (no network/Keychain/cache)\n- **transcript.go** β Tool usage extraction from conversation history (last ~100 lines)\n\n---\n\n## Performance\n\n### Benchmark Results\n\n**Test Environment:**\n\n- Platform: macOS (Apple Silicon)\n- Go: 1.24.13\n- Runs: 20 iterations (minimal), 10 iterations (full)\n\n| Mode | Min | Max | Average | Budget |\n| ------------------------ | ---- | ---- | -------- | ----------- |\n| **Minimal** (stdin-only) | 0ms | 20ms | **6ms** | 300ms (2%) |\n| **Full** (all features) | 30ms | 80ms | **45ms** | 300ms (15%) |\n\n### Breakdown by Feature\n\n| Feature | Added Latency | Notes |\n| --------------------- | ------------- | ------------------------------------------- |\n| JSON parsing + render | ~6ms | Base operation |\n| Git status | +20-40ms | 1s timeout, graceful fail |\n| Transcript parsing | +10-30ms | Last 100 lines only |\n| Quota (rate_limits) | +0ms | Parsed directly from stdin, no network call |\n\n**Optimizations:**\n\n- Compiled Go binary (no interpreter startup)\n- Quota read directly from stdin (no network call, no caching needed)\n- Tail-only transcript parsing (vs full file scan)\n- 1-second timeout on git operations\n- Zero external dependencies (stdlib only)\n\n---\n\n## Development\n\n### Project Commands\n\n```bash\nmake build # Compile to build/howl\nmake install # Copy to ~/.claude/hud/howl\nmake clean # Remove build artifacts\nmake test # Smoke test with sample JSON input\nmake unit-test # Run unit tests\nmake release-dry # Test GoReleaser locally (snapshot)\nmake release-check # Validate .goreleaser.yaml\n```\n\n### Adding New Metrics\n\n1. Add field to `Metrics` struct in `internal/metrics.go`\n2. Implement calculation function\n3. Call in `ComputeMetrics()`\n4. Add render function in `internal/render.go`\n5. Integrate into layout (normal/danger modes)\n\nExample:\n\n```go\n// metrics.go\ntype Metrics struct {\n // ...\n NewMetric *int\n}\n\nfunc calcNewMetric(d *StdinData) *int {\n // calculation logic\n}\n\n// render.go\nfunc renderNewMetric(val int) string {\n return fmt.Sprintf(\"%s%d%s\", color, val, Reset)\n}\n```\n\n---\n\n\n\n## Configuration βοΈ\n\n### Custom Thresholds\n\nAll 15 color breakpoints and the danger mode trigger are configurable via `~/.claude/hud/config.json`:\n\n```json\n{\n \"preset\": \"full\",\n \"thresholds\": {\n \"context_danger\": 92,\n \"context_warning\": 80,\n \"session_cost_high\": 20.0,\n \"quota_high\": 90\n }\n}\n```\n\nOnly specified values override defaults β omitted fields keep their default values.\n\n| Group | Thresholds | Defaults | Effect |\n| ----------------- | ----------------------------------------------------------- | ---------------------------- | -------------------------------------------- |\n| **Context** | `context_danger`, `context_warning`, `context_moderate` | 85%, 70%, 50% | Danger mode trigger, warning/moderate colors |\n| **Session Cost** | `session_cost_high`, `session_cost_medium` | $5.00, $1.00 | Cost display color |\n| **Cache** | `cache_excellent`, `cache_good` | 80%, 50% | Cache efficiency color |\n| **API Wait** | `wait_high`, `wait_medium` | 60%, 35% | API wait ratio color |\n| **Cost Velocity** | `cost_velocity_high`, `cost_velocity_medium` | $0.50, $0.10/min | Cost velocity color |\n| **Quota** | `quota_critical`, `quota_low`, `quota_medium`, `quota_high` | 10%, 25%, 50%, 75% remaining | Quota color bands |\n\n**Interactive setup:** Run `/howl:threshold` in Claude Code to adjust values conversationally β choose a group, set values, and see before/after comparisons.\n\n**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.\n\nChanges apply on the next refresh (~300ms) β no restart needed.\n\n---\n\n\n\n## Troubleshooting π\n\n### Quota shows `?` or is absent\n\n- Not a Claude.ai subscriber (quota only available for subscribers)\n- Before the first API response in the session (quota field appears after the first call)\n- Claude Code older than 2.1.80 (the `rate_limits` stdin field was added in 2.1.80)\n- Each quota window (`five_hour`/`seven_day`) can be independently absent β no bar renders for that window rather than showing a fake 0%\n- Fallback: Quota display is optional, all other metrics still work\n\n### Git branch not showing\n\n- Not a git repository\n- Git timeout (1s) exceeded\n- Solution: Initialize git or ignore (graceful degradation)\n\n### Tools line empty\n\n- Transcript file not accessible\n- Session just started (no tools used yet)\n- Solution: Wait for tool usage or check transcript path\n\n### Performance slower than expected\n\n- Large transcript file (>10MB)\n- Solution: Transcript parses last 100 lines only; quota has zero latency (read from stdin)\n\n---\n\n## Why Howl?\n\nHowl was created to solve specific pain points with existing Claude Code statusline tools.\n\n### Comparison\n\n| Feature | claude-hud | Howl |\n| ------------------ | --------------- | ---------------------------- |\n| Cold start | ~70ms (Node.js) | ~10ms (Go) |\n| Dependencies | npm ecosystem | Zero (stdlib only) |\n| Context display | % only | Absolute (500K/1M) |\n| Metrics count | 3-5 | 17 |\n| 1M context support | β | β
|\n| Quota source | β Missing | β
stdin `rate_limits` field |\n\n### What Makes Howl Different\n\n- **Zero-latency quota** β Reads `rate_limits` directly from stdin (no network call, no Keychain)\n- **Rich metrics** β 17 distinct indicators across 2-4 display lines\n- **Go performance** β ~10ms cold start, 5.6MB binary, zero dependencies\n- **1M context ready** β Adaptive K/M formatting for large windows\n- **Width-aware rendering** β Tool/agent line adapts to terminal width via `COLUMNS`\n\n---\n\n\n\n## Roadmap πΊοΈ\n\n- [x] Configuration file support (`~/.claude/hud/config.json`) β _Available in v1.3.0+_\n- [x] Auto-sync plugin.json version in release pipeline β _Available in v1.4.0+_\n- [x] Custom thresholds β 15 configurable color breakpoints and danger mode trigger β _Available in v1.5.0+_\n- [ ] Custom color schemes\n- [ ] Plugin system for custom metrics\n- [ ] Windows support\n\n---\n\n\n\n## Contributing π€\n\nThis is a personal tool for the AiScream project. Feedback and bug reports welcome!\n\n---\n\n\n\n## License π\n\nMIT License β see [LICENSE](LICENSE) file for details.\n\nFor release history and detailed changes, see [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n\n\n## Credits π\n\n**Project:** [ai-screams/howl](https://github.com/ai-screams/howl)
\n**Author:** pignuante
\n**Inspired by:** [claude-hud](https://github.com/jarrodwatts/claude-hud) by Jarrod Watts\n\nBuilt with β€οΈ and Claude Code.\n",
"bytes": 24010,
"sha": "a653be6b923831ab9a1c40c8755c518e15472eb01fe2301ffa06e154169ec11c",
"repo_slug": "ai-screams/howl",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_ai_screams_howl_howl_b3a6fcfb/readme"
}