Core Analysis¶

Project Positioning: Claude HUD addresses three concrete observability gaps inside Claude Code sessions: accurate context/token visualization, real-time tools/agent activity tracking, and an always-visible in-terminal summary of project/branch and todo progress.

Technical Analysis¶

• Data sources: It uses Claude Code’s statusline API and native token/context data rather than estimates, ensuring accuracy.
• Event parsing: It consumes transcript JSONL to extract read/write/grep tool calls, sub-agent states, and todo updates, converting model behavior into visual lines.
• Rendering and latency: With ~300ms update cadence, the stdin→plugin→stdout stream renders beneath the input line without requiring extra windows or tmux.

Practical Recommendations¶

1. After install, run /claude-hud:setup and pick a preset (Full/Essential/Minimal) to get started quickly.
2. Enable detailed context and usage lines for long sessions (Max/1M-context) to avoid hitting window limits unexpectedly.
3. Use the HUD as your primary quick-check when debugging file operations or sub-agent workflows; cross-check with session transcripts for critical steps.

Important Notice: Usage display depends on Anthropic’s usage API and OAuth and is available only to Pro/Max/Team account types; API-key-only workflows cannot get equivalent usage data.

Summary: By relying on native data, real-time parsing, and in-terminal rendering, Claude HUD fills a critical observability gap for users who need fine-grained session monitoring and debugging.

Core Analysis¶

Why this architecture: The project uses Claude Code’s statusline API as the rendering channel and consumes transcript JSONL plus native token data as its event and metric sources. This pairing enables high-precision, low-latency observability without disrupting the terminal workflow.

Technical Advantages¶

• Native terminal integration: Statusline output keeps the HUD visible without extra windows or tmux, creating a seamless UX.
• Accurate metrics: Direct access to Claude Code’s token/context data avoids estimation inaccuracies, crucial for very large contexts (1M).
• Real-time behavioral visualization: Parsing transcript JSONL turns model tool calls, file ops, and sub-agent activity into human-readable lines; ~300ms updates aid real-time debugging.

Limitations and Risks¶

1. Platform coupling: Depends on Claude Code’s statusline API and transcript format; platform changes require plugin updates.
2. Scope limitation: Runs only inside Claude Code and cannot directly serve external Anthropic API clients or other editors.
3. Account & permission dependencies: Usage display requires OAuth and Pro/Max/Team account types; API key users won’t get equivalent data.

Important Notice: The architecture trades platform specificity for accuracy and responsiveness. Evaluate adoption only if Claude Code is your primary workflow.

Summary: This architecture delivers strong observability benefits within Claude Code but has limited portability and some account-dependent features.

Core Analysis¶

Key question: How to use HUD’s tool/agent activity lines to efficiently locate model-triggered issues?

Technical Analysis¶

• Event visualization: The HUD parses transcript JSONL into concise lines for tool calls (read/edit/grep), sub-agent states, and todo progress. Examples include Edit: auth.ts | Read ×3 | Grep ×2 and explore [haiku]: Finding auth code (2m 15s).
• Update cadence & granularity: ~300ms updates provide near-real-time awareness of model IO and agent activity.
• Localization workflow: Tool lines point to specific files and counts; agent lines show agent name, current objective, and runtime; todo lines show completion. Together they narrow down the issue to file, agent, or task level.

Practical Debugging Steps¶

1. Identify the activity origin: If HUD shows frequent read/edit/grep, open the referenced files and inspect recent changes or context.
2. Track agent name & task: Use agent lines to detect stuck or retrying agents; then examine the transcript for agent start conditions and execution logs.
3. Use todo lines to assess priority: Repeatedly failing todo items point to agent or tool faults rather than user task ordering.
4. Backtrace with transcripts and diffs: Treat HUD as a first indicator; confirm with full transcripts and git diffs for root-cause analysis.

Important Notice: HUD provides summaries, not full logs. Complex race conditions or concurrent agent issues still require transcript inspection and richer logs.

Summary: Use HUD as your fast triage view to focus on problematic files or agents, accelerating fault localization, and then validate and fix the root cause using the complete transcript and diffs.

Core Analysis¶

Key issue: Early-stage failures mainly stem from platform restrictions, network settings, and account-type differences. The README calls out key caveats, but practical attention is still needed to avoid common pitfalls.

Common Problems and Causes¶

• Linux install failure (EXDEV): Often caused by /tmp mounted as tmpfs, leading to cross-device link errors.
• Usage not visible: Usage display is available only to OAuth-enabled Pro/Max/Team accounts; API-key workflows won’t see it.
• Network/proxy issues: Missing HTTPS_PROXY or too-short timeouts can break usage queries.
• Advanced config friction: Editing ~/.claude/plugins/claude-hud/config.json requires understanding thresholds and color settings.

Practical Recommendations¶

1. Linux pre-step: Before install, run:
   mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude then perform /plugin install claude-hud.
2. Usage visibility: Ensure you have OAuth and a Pro/Max/Team account if you need usage metrics.
3. Network & timeouts: Set HTTPS_PROXY in proxied environments and increase CLAUDE_HUD_USAGE_TIMEOUT_MS and cache TTLs to reduce failures.
4. Config management: Maintain a shared config.json for teams and start from a preset to avoid information overload.

Important Notice: Some features are account- and network-dependent. If OAuth is unavailable, expect usage metrics to be absent.

Summary: Following the README TMPDIR workaround, using the setup guide, and tuning proxy/timeouts and caching will avoid most installation and initial configuration issues.

Core Analysis¶

Key question: Identify the plugin’s suitable use cases and hard limitations so you can decide whether to adopt it or seek alternatives.

Ideal Use Cases¶

• In-terminal development and debugging: Users of Claude Code terminal/editor workflows who want session health and activity details in one view.
• Long-context and billing-sensitive sessions: Max/1M-context sessions or token-sensitive workflows that benefit from accurate context bars and usage displays.
• Tools/agent developers: Teams needing to watch model file reads/writes, grep calls, or sub-agent launches in real time.

Clear Limitations¶

1. Claude Code-only: Not applicable to direct Anthropic API clients or other editors/IDEs.
2. Usage visibility constraints: Usage requires OAuth and a Pro/Max/Team account. API-key users and custom Anthropic base URLs may not see usage data.
3. Network dependence: Offline or restricted networks disable usage and some live query features.

Alternatives¶

• If not using Claude Code: collect session/token metadata at the server/proxy layer and visualize with Prometheus/Grafana or a custom dashboard.
• For cross-editor support: use or build plugins that target multiple IDEs or do backend transcript parsing and alerting.

Important Notice: Treat HUD as an instant observability tool for Claude Code, not a cross-platform monitoring solution.

Summary: HUD is highly valuable when your workflow centers on Claude Code and needs real-time session visibility. Otherwise consider logging/monitoring infrastructures or IDE-agnostic plugins.

Core Analysis¶

Key issue: Teams and long-running sessions need consistent HUD displays and thresholds across various terminals so everyone shares the same observability experience.

Technical Analysis¶

• Centralized config: HUD supports presets and direct editing of ~/.claude/plugins/claude-hud/config.json, with fields for colors, thresholds, pathLevels, cache, and timeouts.
• Network variability: Usage queries depend on network and OAuth; tuning cacheTtlSeconds and failureCacheTtlSeconds reduces the impact of transient network issues.
• Layout adaptability: Expanded/compact layouts and pathLevels (1–3) let you fit HUD density to terminal width and preferences.

Practical Recommendations¶

1. Version the config: Store a team config.json in the repo or manage via dotfiles, and symlink it to ~/.claude/plugins/claude-hud/config.json on each machine.
2. Start from a preset: Use Essential as a default to avoid overload, and let power users opt into Full features.
3. Tune caching & timeouts: Increase cacheTtlSeconds and CLAUDE_HUD_USAGE_TIMEOUT_MS in flaky networks, and configure HTTP proxy env vars for stable usage queries.
4. Standardize thresholds/colors: Define common thresholds (e.g., context ≥80% as warning) and bake them into the shared config.json.

Important Notice: Usage visibility is account-dependent. Teams should ensure OAuth-compatible accounts or accept that some members may not see usage metrics.

Summary: Versioned config, preset-based onboarding, network-aware cache/timeouts, and standardized thresholds let teams maintain consistent HUD behavior across terminals.