statusline-generator

ステータスラインジェネレーター

Claude Code 向けの、信頼できる唯一の情報源となるステータスラインです。1 つのスクリプトで 2 つのレイアウトに対応し、最初から最後まで自己検証します。

クイックヘルスチェック（問題が起きたらまず実行）

ステータスラインの動作がおかしい場合は、最初にこれを実行してください。これにより、「設定したのに動かない」という報告の大半を占める、表面化しない失敗を検出できます。

bash scripts/health_check.sh

次の 4 つのレイヤーを検証します。

1. ~/.claude/statusline.sh が存在し、実行可能であること。chmod +x の付け忘れが、表面化しない失敗の原因として最も多くあります。Claude Code がスクリプトを実行しようとしますが、exec が失敗し、ステータスラインが空白になります。
2. ~/.claude/settings.json に、スクリプトを参照する有効な statusLine ブロックがあること。
3. 完全なデータ、トークン数が 0 の場合、フィールドの欠落、$HOME パスの短縮、ゼロフォークでの Git ブランチ描画を確認するモック stdin テスト（合成 .git/HEAD を使用し、git バイナリは不要です）。
4. 以前に CLAUDE_STATUSLINE_DEBUG=1 を指定して実行していた場合は、/tmp/.claude-statusline-last-stdin.json から実際の stdin を再生します。

各失敗について、修正用のコマンドを 1 行で表示します。復旧のためにドキュメントを読む必要はありません。

クイックインストール

bash scripts/install_statusline.sh

このスクリプトは次の処理を行います。

• 既存の ~/.claude/statusline.sh と settings.json をバックアップします。
• generate_statusline.sh を ~/.claude/statusline.sh にコピーし、chmod +x を実行します。
• jq を使って settings.json の statusLine ブロックを更新します（ほかの設定は保持します）。
• 必ず health_check.sh を実行して結果を表示します。検証に合格するまで、インストールは「完了」しません。

Claude Code を再起動するか、新しいメッセージを送信すると、ステータスラインが更新されます。

使用できる機能

デフォルト — 最小限の 1 行レイアウト

~/code/myproject  [main]  Opus 4.7 (1M context)  ctx: 108K / 1M

必要な情報だけを表示します。短縮パス、Git ブランチ、モデル名、トークンの絶対数です。色、コスト、割合は表示しません。ブランチは ゼロフォーク で読み取ります。スクリプトは git を起動する代わりに .git/HEAD を通常のファイルとして読み込みます（worktree／サブモジュールの gitdir: 間接参照と、detached HEAD の短縮 SHA の処理に対応しています）。そのためコストはかからず、git バイナリがないホストでも動作します。

フル — コストと Git を含む複数行レイアウト

シェルプロファイルで CLAUDE_STATUSLINE_LAYOUT=full を設定すると有効になります。

alex (Sonnet 4.6) [$0.42/$25.93]  ctx: 108K/1M (11%)
~/code/myproject
[git:main*+]

• 1 行目：ユーザー、モデル、ccusage のセッション／日次コスト、色分けされた ctx（緑 ≤50%、黄色 51～80%、赤 >80%）。
• 2 行目：短縮パス。
• 3 行目：変更済みの場合は *、未追跡の場合は + を付けた Git ブランチ。

レイアウトの切り替え方法

このスクリプトはフラグではなく環境変数からレイアウトを読み取ります（Claude Code は stdin で JSON を渡すため、フラグを使うと競合します）。~/.zshrc または ~/.bashrc に設定してください。

# Minimal (default — same as not setting it)
export CLAUDE_STATUSLINE_LAYOUT=minimal

# Full
export CLAUDE_STATUSLINE_LAYOUT=full

シェルを再起動するか、rc ファイルを source して、Claude Code に変更が引き継がれるようにしてから、メッセージを送信してください。ステータスラインは 300ms 以内に更新されます。

stdin のデバッグキャプチャ

Claude Code がスクリプトに送信する JSON を正確に確認するには、次のようにします。

export CLAUDE_STATUSLINE_DEBUG=1

呼び出しのたびに stdin が /tmp/.claude-statusline-last-stdin.json に書き込まれます（更新のたびに上書きされます）。jq . で確認してください。次のような用途に便利です。

• フィールドが期待どおりに表示されない理由の診断。
• 実際の入力を使ったスクリプトの再実行：cat /tmp/.claude-statusline-last-stdin.json | ~/.claude/statusline.sh。
• バグ報告の提出 — ダンプを正確な根拠として貼り付けます。

作成ルール（このスキルがこの形になっている理由）

本番環境での 3 つの失敗パターンを受けて、現在の設計になりました。これらはドキュメントだけでなく、すべてコードで防止しています。

ルール 1 — 必ず chmod +x を実行し、必ず実行して検証する

あらゆるステータスラインで、表面化しない失敗の最大の原因は、実行ビットのないスクリプトです。Claude Code の exec は何も表示せずに失敗し、エラーも出ないままバーが空白になります。install_statusline.sh は必ず chmod +x を実行し、health_check.sh は実行ビットがない場合に警告します。ステータスラインスクリプトを自分で作成または編集した場合は、完了とする前にモックテストしてください。：echo '{}' | bash your-script.sh。

ルール 2 — 「設定完了」はエビデンスがなければ意味がない

「ファイルを書き込み、settings.json を更新した」ことは「スクリプトが実行され、期待どおりの出力が得られた」ことと同じではありません。そのため install_statusline.sh は常に最後に health_check.sh を実行し、いずれかのチェックが失敗した場合は非ゼロで終了します。エビデンスを欠いたエージェントからの「完了！」という報告は、すべて疑わしいものとして扱ってください。

ルール 3 — ステータスラインはホットパスである：正しさだけでなく、サブプロセスの予算を意識する

ステータスラインのスクリプトは UI の演出に見えますが、同時に動作するすべてのエージェントセッションにおいて、リフレッシュのたびに実行されます。それが起動するものは何であれ、リフレッシュ頻度 × 稼働中セッション数で、一日中積み重なっていきます。多くのセッションを同時に実行しているマシンで計測したところ、パッケージランナー方式のステータスライン（bunx <pkg>@latest 形式で、リフレッシュごとにレジストリを再解決しロックファイルを書き換え、さらに git status + git branch を実行するもの）はリフレッシュあたり約 0.4 秒の CPU を消費しましたが、このスクリプトは約 0.01 秒です。多くのセッションにまたがると、その差はマシン全体のプロセス churn、発熱、バッテリーの無視できない割合になります。実際のバッテリー消費調査（2026-07）では、ステータスラインが主要な原因の一つとして特定されました。

具体的には：

• リフレッシュ時にパッケージを解決しないでください。 statusLine.command に bunx/npx の @latest を入れないでください — 一度ピン留めしてインストールするか、ローカルスクリプトを使用してください。
• ブランチ取得のために git を起動しないでください。 .git/HEAD をファイルとして読んでください（スクリプト内の git_branch_fast を参照）— 同じ結果が、サブプロセスゼロで得られます。
• git status（ダーティ状態）は贅沢品として扱ってください。 これはリフレッシュのたびにワークツリーを走査します。フルレイアウトのみがこれを実行し、しかも明示的に有効化された場合に限られます。
• 予算：ステータスラインのリフレッシュは一桁ミリ秒、フォークはせいぜい数回に抑えるべきです（ここでは jq 1 回 + awk 1 回）。

現場レベルの落とし穴（セッション開始時の used_percentage が null、Claude Code のバージョン間での total_input_tokens の意味論、ハードコードされた context_window_size）については、references/context-window-schema.md を参照してください。

カスタマイズ

色、カスタムセグメント（ホスト名、時刻など）、コスト追跡の無効化については、references/customization.md を参照してください。

依存関係

スクリプトは利用可能なツールを自動検出し、段階的に機能を縮退させます：

ツール	必要な機能	フォールバック
jq	JSON 解析（推奨）	python3 にフォールバック
python3	JSON 解析のフォールバック	cwd のみ
awk	トークンの K/M フォーマット	両方のレイアウトで必須
git	ダーティ状態の */+ マーカー（フルレイアウトのみ — ミニマルは git なしで .git/HEAD からブランチを読み取ります）	存在しない場合、またはリポジトリ内でない場合はサイレントにスキップ
ccusage	コスト（フルレイアウト）	存在しない場合はサイレントにスキップ

macOS でのインストール：brew install jq。Debian/Ubuntu では：apt install jq。

トラブルシューティング

症状別の診断については、references/troubleshooting-decision-tree.md を参照してください。以下の項目を順にたどります：

1. ステータスラインが空、または更新されない（chmod が原因）
2. ctx セグメントが欠落または誤っている（フィールドの落とし穴）
3. パーセンテージではなくトークン数が欲しい（レイアウトの切り替え）
4. 色が生のエスケープコードとして表示される（ターミナルの互換性）
5. Git セグメントが欠落している（フルレイアウト）
6. コストセグメントが欠落している（ccusage / キャッシュ）
7. 編集が反映されない（パスの不一致）
8. リフレッシュが遅い（jq と python3）

リソース

ファイル	用途
scripts/generate_statusline.sh	ステータスラインのスクリプトです。唯一の信頼できる情報源です。CLAUDE_STATUSLINE_LAYOUT を使って 2 種類のレイアウトを選択できます。
scripts/install_statusline.sh	冪等性のあるインストーラーです。バックアップ、コピー、chmod、settings.json の設定、ヘルスチェックを実行します。
scripts/health_check.sh	4 層の検証を行います。ファイルの権限、settings.json の設定、標準入力を使ったモックテスト、実際の標準入力の再生を確認します。
references/troubleshooting-decision-tree.md	症状に応じた診断フローチャートです。ステータスラインが正常に動作しない場合に読み込みます。
references/customization.md	色の変更、カスタムセグメント、しきい値の調整、1 行表示の全機能レイアウトについて説明します。ユーザーがステータスラインの見た目を変更したい場合に読み込みます。
references/context-window-schema.md	Claude Code のステータスライン JSON スキーマです。各フィールドと、バージョン間における current_usage と total_input_tokens の意味の違いを説明します。
references/color_codes.md	ANSI カラーコードのリファレンスです。色をカスタマイズする場合に読み込みます。
references/ccusage_integration.md	ccusage との連携に関する詳細です。キャッシュ、JSON の形式、トラブルシューティングについて説明します。コスト関連の問題がある場合に読み込みます。