Claude Code の足もとに、18分類の計器盤を。ステータスラインを作りました

こんにちは、プロマリの紫です。今回は、私がふだん使っている AI のコーディング支援ツール、Claude Codeの画面の話です。入力欄のすぐ下に、1行だけ状態を表示できる場所があります。そこを18の分類に分けた、15行ほどの計器盤に作り変えました。レート制限の残り、料金の見込み、作業の密度、ブランチの状態までが、視線を少し落とすだけで読めます。この記事では、そのステータスラインを、数字の出どころから画面への並べ方、点滅の作り方、導入と検証まで、画面の数字を式で検算しながら読み解いていきます。

点線の付いた用語は、その言葉を押すと詳しい説明が開きます。意味、身近なたとえ、この実装での使い方を順に読めます。キーボードではTabで用語へ移動し、EnterまたはSpaceで開き、Escapeで本文へ戻れます。各ページで最初に出る用語から参照できるようにしました。

この記事は5ページあります。1ページ目で、完成した画面と、ステータスラインが動くしくみを確かめます。2ページ目では、画面の数字がどこから来ているのかと、その集め方の工夫を読みます。3ページ目は、使用率のような「率」を、次の行動が決まる倍率・残り時間・金額へ翻訳する計算です。4ページ目で、端末に黙って切られないための並べ方と、点滅の作り方を見て、5ページ目で導入・検証の方法と、あえて表示しないと決めたものの話をします。図は20点です。記事に出てくる画面は、2026年9月30日に私の端末に表示されていたものの形をそのまま使い、金額やアカウント名などはサンプルの値に置き換えました。サンプルの値も、画面の中の式が成り立つように選んであります。式はすべて実装のコードから写しました。

入力欄の下に並ぶ、15行の計器盤

まずは完成した画面から見てください。次の文字は、この記事を書き始めた日の早朝、Claude Code の入力欄の下に表示されていた画面です。行の並び・使用率・時間はそのままで、金額・アカウント名・リポジトリ名・会話の名前はサンプルに置き換えています。

📉 Forecast │ 7d 枯渇まで 6h18m (reset前)
🧠 Context │ █░░░░░░░░░ 14% 136k/1.00M 残 864k
⚡ Claude 5h ███░░ 68% 🔄 4h29m Pace ×6.7 7d ██░░░ 45% 🔄 6d7h Pace ×4.5
🤖 Codex 7d █████ 100% 🔄 3d23h 💳 Bal $50
💰 Cost │ Sess $1.20 │ Today $48.50 │ Blk $20.00 (残 4h19m) │ Est $193
🔥 Burn │ $40.00/h │ ⏰ 4m (API 0m) │ Active 0m │ Streak 0m ┃ 📈 KPI │ $/Turn 1.2
🚀 Perf │ Parallel ×0.09 │ Thruput 6,451 tok/s │ ErrRate 2.9% │ CacheSave 53%
📦 Cache │ Hit 59% 残 59m │ 🧊 Cold 136k ┃ 📊 Tokens │ In 136k / Out 861
🔧 Work │ Turns ×1 │ Tools ×34 Bash3/Explanatory2/Agent2 ❌ Err 1
🌿 Git │ develop │ 📝 3 Files │ 📚 2 Stash │ 📅 Cmt 7m
🔖 Session │ ブログ記事の執筆
🧭 Env │ Opus 5.5 │ Mode medium·think │ 📂 sample-repo │ Style Explanatory
💻 System │ 🕐 04:40 │ CPU 8.4/10c │ 🧮 Mem 6.4G │ 💾 Disk 677G │ 🔌 Bat 100%
🧾 Meta │ ⛵ Proc ×4 │ 👤 （伏せ字） │ v2.1.285

一見すると記号と数字の洪水ですが、読み方には決まりがあります。どの行も、左端の「絵文字＋分類名」から始まります。📉 Forecast、🧠 Context、⚡ Claude と、行の頭だけを上から拾っていけば、その行に何が書いてあるかが分かります。分類名の右には、│ で区切られた小さな値のかたまりが並びます。この記事では、このかたまりをチップと呼びます。幅に余裕があるときは、🔥 Burn の行の右端のように、┃ をはさんで次の分類（📈 KPI）が同じ行に乗ります。

この朝の画面を、上から少し読んでみます。いちばん上の📉 Forecast は、「7日の枠が、このペースだと6時間18分で尽きる。しかも枠がリセットされるより前に」という警告です。すぐ下の⚡ Claude の行を見ると、5時間の枠を68%、7日の枠を45%使っていて、どちらにも Pace という倍率が付いています。🤖 Codex の行は100%、つまり別の AI ツールの週の枠は、すでに使い切っています。💰 Cost の行の Est $193 は、いまの使い方がこのまま続いたときの、5時間ブロックの終わりの金額の見込みです。

ここまで読むと、この朝の状況がかなり具体的に見えてきます。「Codex はもう使えない。Claude の7日枠も、このペースだと今日のうちに尽きる。重い調べものは控えめにして、作業の順番を考え直したほうがよい」。数字を読んだ結果が、次にとる行動にそのままつながること。これが、この計器盤で目指したことです。

行ごとの意味を、ひととおり表にしておきます。細かい計算は3ページ目以降で1つずつ確かめるので、ここでは「こんな分類がある」と眺めるだけで大丈夫です。

ステータスラインは、コマンドの標準出力

次は、この画面がどうやって作られているかです。しくみは、拍子抜けするほど単純です。Claude Code の設定ファイルsettings.jsonに「ステータスラインにはこのコマンドを使う」と書いておくと、Claude Code はそのコマンドを繰り返し呼び出します。呼び出すときに、いまの状態をJSONにして、コマンドの標準入力へ流し込みます。コマンドは、それを読んで文字を組み立て、標準出力へ書き出す。書き出された文字が、そのまま入力欄の下に並びます。

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

設定はこれだけです。command に書いた statusline.sh は、中で Python の statusline.py を起動するだけの3行のシェルスクリプトで、本体は1,000行ほどの Python です。標準入力に届く JSON には、たとえば次のような項目が入っています。

{
  "model": { "display_name": "Opus 5.5" },
  "context_window": { "context_window_size": 1000000, "used_percentage": 14 },
  "cost": { "total_cost_usd": 0.96, "total_duration_ms": 240000 },
  "rate_limits": { "five_hour": { "used_percentage": 68, "resets_at": 1790000000 } },
  "session_id": "…",
  "transcript_path": "…"
}

モデルの名前、コンテキストの使用率、料金、レート制限の枠。画面の数字のうち、かなりの部分はこの JSON にそのまま入っています。ステータスラインのコマンドの仕事は、届いた値を読み、足りない値をよそから集め、読みやすい順に並べて print することです。

ここで1つ、大事な性質があります。公式ドキュメントによると、ステータスラインのコマンドは、会話が更新されるたびに呼ばれ、呼び出しは300ミリ秒の間隔で間引かれます。つまり、会話が動いているあいだ、このスクリプトは1秒に何回も起動されます。反対に、何も起きていないときは呼ばれません。この「頻繁に、ただし会話が動いているときだけ呼ばれる」という性質は、この記事で何度も顔を出します。2ページ目ではキャッシュの設計を縛る制約として、3ページ目では作業時間を測るセンサーとして、4ページ目では点滅を作る仕掛けとして、です。

いちばん小さなステータスラインなら、次の数行で作れます。標準入力の JSON を読み、モデル名と使用率を1行 print するだけです。

import json, sys

data = json.load(sys.stdin)
model = data["model"]["display_name"]
used = data["context_window"]["used_percentage"]
print(f"{model} │ Context {used:.0f}%")

この5行から、15行の計器盤までの距離が、この記事の中身です。値を足していくだけなら簡単そうに見えますが、実際に作ってみると、「最初の描画には値が無い」「行の右端が黙って消える」「点滅の命令が効かない」「作業を始めた直後の比率が1時間あたり1万行を超える」といった、エラーにならない困りごとに次々ぶつかりました。この記事は、その1つ1つを、どう見つけて、どう直したかの記録でもあります。

なぜ、ここまで並べたのか

ここで、そもそもの動機にふれておきます。Claude Code を長い時間使っていると、気になることが増えていきます。枠はあとどれくらい残っているのか。会話の机（コンテキスト）は、あとどれくらい広げられるのか。今日はいくら分使ったのか。どれも、聞けば分かりますし、別のコマンドを打っても分かります。ただ、聞かないと分からない情報は、気づいたときには手遅れになりがちです。

この計器盤も、作り始めは「⚡ Claude のレート制限を画面に出したい」という1つの願いからでした。夢中で作業をしていると、気づいたら5時間の枠を使い切っていた、ということが起こりえます。枠を使い切ると、リセットまで待つしかありません。もし1時間前に「このペースだと、リセットの前に尽きます」と分かっていれば、調べものの深さを落としたり、別の作業に切り替えたりできます。必要なのは、あとから確かめる帳簿ではなく、運転しながら目に入る計器です。レート制限の1行から始めて、ほしい数字を1つずつ足していった結果が、いまの18分類です。

もう1つの動機は、数字の意味をそろえたかったことです。使用率68%と聞いても、それが多いのか少ないのかは、枠のどの時点での68%かで変わります。リセット直前の68%なら余裕ですが、始まって30分の68%なら大変な速さです。そこで、生の数字を並べるだけでなく、「速すぎる」「尽きる」「いくらになる」という、判断に直結する言葉へ翻訳してから表示することにしました。この翻訳の中身は、3ページ目で式ごと確かめます。

先に、どういう方針で並べたのかを書いておきます。表示するのは、見たあとの行動が変わる数字だけにしました。値が取れない分類は、空の枠を残さず、行ごと消します。

上から読む順番が、そのまま優先度

18の分類は、好きな順に並べているわけではありません。上にあるほど、今すぐの行動に効くという順番です。いちばん上は、今すぐ手を止めるべき警告（🚨 Alert・📉 Forecast）。その下に、あとどれだけ使えるかという残量（🧠 Context・⚡ Claude・🤖 Codex）。次にお金（💰 Cost・🔥 Burn）、使い方の効率（📈 KPI・🚀 Perf・📦 Cache・📊 Tokens）、いまの作業（🔧 Work・🌿 Git・🔖 Session）と続き、いちばん下に、どこで動いているかという環境（🧭 Env・💻 System・🧾 Meta・🎵 Music）が来ます。

この順番にしたのは、人の目が上から下へ読むからです。画面を一瞬見たとき、最初に目に入る行ほど、見逃したときの損が大きいものを置きたい。平常時は、上の2つの警告の行は出ていないので、画面は🧠 Context から始まります。何かあったときだけ、その上に赤い行が割り込んでくる、という作りです。ちなみに、冒頭の画面で📉 Forecast がいちばん上にあったのは、まさにその「何かあったとき」だったからです。

実装では、この順番を1つの一覧として書いています。色・分類名・チップの入れ物の組を、上から順に並べたものです。

for col, name, g in (
    # 重要度の高い順（警告 → 残量 → コスト → 効率 → 作業状態 → 素性 → 環境）
    (C_BAD, "🚨 Alert", parts_alert),
    (C_BAD, "📉 Forecast", parts_fcast),
    (C_MODEL, "🧠 Context", parts2),
    (None, None, parts_claude),          # 行内に ⚡ Claude ヘッダを含む
    (None, None, parts_codex),           # 行内に 🤖 Codex ヘッダを含む
    (C_MONEY, "💰 Cost", parts3),
    (C_BAD, "🔥 Burn", parts_burn),
    # …（📈 KPI から 🎵 Music まで同じ形で続く）
):
    if not g:
        continue
    groups.append((col, name, g))

最後の2行が、「値が無い分類は行ごと消す」の正体です。チップの入れ物（g）が空なら、その分類は groups に入らず、画面に何も残りません。表示の順番を変えたくなったら、この一覧の行を入れ替えるだけで済みます。

チップの文法：絵文字、ラベル、値

1つ1つのチップにも、決まりを作りました。たくさんの数字が並ぶ画面で、「この 59% は何の59%か」を迷わせないためです。決まりは4つあります。

ラベルを英語にしたのは、幅の節約と、見た目のそろい方のためです。日本語は1文字で2マスの幅を取るので、同じ意味でも英語のほうが短く収まります（この「マス」の話は4ページ目で詳しく扱います）。一方で、「残 864k」や「枯渇まで」のように、日本語のほうが一瞬で意味が伝わるところは日本語のままにしました。英語か日本語かを一律に決めるより、その場所で一番速く読めるほうを選ぶほうが、計器としては読みやすくなります。

色は、重さの目盛り

ラベルと並んで、もう1つの読みやすさの支えが色です。この計器盤では、色を飾りとしてではなく、その数字がどれくらい危ないかを示す目盛りとして使っています。緑は余裕がある、黄色は気にし始める、赤は手を打つ、の3段です。どの数字にも同じ3段を当てるので、細かい値を読まなくても、色だけで行のどこが危ないかが分かります。

def sev(pct, warn=50, bad=80):
    return C_OK if pct < warn else (C_WARN if pct < bad else C_BAD)


def bar(pct, width=10, warn=50, bad=80):
    pct = max(0.0, min(100.0, pct))
    filled = round(pct / 100 * width)
    return sev(pct, warn, bad) + "█" * filled + C_GRAY + "░" * (width - filled) + R

sev() は、割合を受け取って、緑・黄・赤のどれかの色を返す小さな関数です。何も指定しなければ、50%未満が緑、80%未満が黄色、それ以上が赤です。bar() は、同じ色で █（塗ったマス）と ░（空いたマス）を並べて、横棒のグラフを作ります。🧠 Context の行では10マス、⚡ Claude と🤖 Codex の行では5マスの棒にしています。レートの行には枠が2つ並ぶので、棒を短くして1行に収めるためです。

境目は、数字の性質に合わせて変えています。CPU の負荷は、コアの数に対して70%までを緑、100%までを黄色にしています。CPU は満杯近くまで使っても、すぐに困るとは限らないからです。反対に、🚀 Perf の行の ErrRate（道具の呼び出しが失敗した割合）は、2%未満で緑、5%未満で黄色と、ずっと厳しくしています。失敗は少しでも増えると、やり直しの手間になって返ってくるからです。同じ「赤」でも、何%で赤くするかは、数字ごとに「困り始める点」から決めています。冒頭の画面の ErrRate 2.9% が黄色だったのも、この境目によるものです。