Claude HUD

Claude Code セッションの状態を、入力欄直下のステータスラインに集約するプラグイン（jarrodwatts/claude-hud）。

1 — 概要
役割

Claude HUD は、コンテキスト使用率・ツール実行・サブエージェント・TODO 進捗などを、別ウィンドウや tmux パネルなしで常時表示する Claude Code プラグイン。Claude Code が提供する statusline API に乗り、標準入出力で短いテキスト行を返す。

statuslineネイティブ API
~300ms更新間隔の目安
transcriptツール・エージェント解析
Nativeトークン・rate_limits

コンテキスト窓は Claude Code が報告する値に追従し、大容量セッション（例: 1M コンテキスト）にもスケールする。ツール行・エージェント行・TODO 行は設定でオフが既定で、必要なときだけ有効化する。

2 — 導入
手順
  1. マーケットプレイスを追加: /plugin marketplace add jarrodwatts/claude-hud
  2. プラグインをインストール: /plugin install claude-hud
  3. プラグイン再読込: /reload-plugins
  4. ステータスライン設定: /claude-hud:setup

セットアップ後は Claude Code を再起動し、statusLine 設定を読み込ませる。Windows ではセットアップ後にフル再起動が推奨される。

Linux: /tmp が tmpfs のとき、プラグインインストールで EXDEV: cross-device link not permitted が出ることがある。公式 README のとおり、インストール前に TMPDIR をホーム配下の一時ディレクトリへ向ける（例: mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude）。
Windows: セットアップで JavaScript ランタイムが見つからない場合は Node.js LTS を入れてシェルを開き直し、/claude-hud:setup を再実行する。
3 — 表示内容
デフォルト 2 行

1 行目はモデル名・（識別できれば）プロバイダラベル・プロジェクトパス・git ブランチ。2 行目はコンテキストバーと利用枠（サブスクの rate_limits が stdin に載る場合）。

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

オプション行（/claude-hud:configure で有効化）

  • ツール: 編集中ファイルや Read / Grep などの回数
  • エージェント: サブエージェント名・モデル・経過時間
  • TODO: 現在のタスクと完了数
表示ブロック意味
Project path作業ディレクトリ（表示階層は pathLevels で 1〜3）
Context healthコンテキスト占有率（色は閾値で緑→黄→赤）
Tool activity進行中・完了したツール呼び出しの要約
Agent tracking動いているサブエージェントの状態
Todo progressTODO リストの進捗
4 — データの流れ
I/O

Claude Code が statusline 用に送る stdin の JSON を読み、必要に応じて トランスクリプト（JSONL） からツール・エージェント・TODO を解析する。描画用の短い文字列を stdout に返し、ターミナルが入力欄下に表示する。

flowchart TD CC[Claude Code] -->|stdin JSON| HUD[Claude HUD] CC -->|transcript JSONL| HUD HUD -->|stdout テキスト行| T[ターミナル statusline]
  • 利用枠表示は、stdin の rate_limits を優先。欠落時は設定したローカルスナップショット（display.externalUsagePath）で補完可能。
  • セッションコストは cost.total_cost_usd が来たとき表示（Bedrock / Vertex など一部経路では非表示や 0 表示の扱いあり）。
5 — 設定
対話とファイル

/claude-hud:configure でプリセット・言語・主要トグルを変更できる。色や閾値などの上書きは、プラグイン配下の config.json を直接編集する（README に記載のパスに従う）。

プリセット

プリセット内容
Fullツール・エージェント・TODO・git・usage・所要時間などをすべて表示可能に
Essentialアクティビティ行と git を中心に、情報量を抑える
Minimalモデル名とコンテキストバーのみ

よく触るオプション（抜粋）

キー型・値説明
languageen | zhHUD ラベル言語（既定は英語、中文は明示選択）
lineLayoutexpanded | compact複数行か 1 行に畳むか
pathLevels1〜3プロジェクトパスに含めるディレクトリ深さ
display.showTools などbooleanツール・エージェント・TODO 行の表示（既定はいずれも false 寄りで README 参照）
elementOrderstring[]expanded 時のブロック順。省略した要素は非表示にできる
6 — 要件
実行環境
  • Claude Code v1.0.80 以上
  • macOS / Linux: Node.js 18+ または Bun
  • Windows: Node.js 18+（LTS 推奨）
公式