Claude Codeのステータスライン完全カスタム ― JSON駆動で残量・コスト・健全性を3行表示

前回、CodexとworktreeでAIを並列に走らせた話を書きました。今回はその足場の話 ―― 常時見えているステータスラインの実装です。

結論から: automation-health.sh（launchd/hooks/会話ログなど自律基盤の死活監視スクリプト）を実測したら1回78.23秒かかりました（user 4.43s + system 7.81s、--deepなしでもこれ）。これを毎ターン素直に呼んだら会話が止まります。答えは「300秒キャッシュ＋バックグラウンド起動」で、キャッシュヒット時はサブプロセス起動ゼロ・ファイルread1回だけです。この記事はその実装を全部見せます。

困りごと：残量が見えないと無人ジョブを止め損なう

前々回の自律ループ記事で「コスト枠を数値で先にチェックする」仕組みを書きましたが、そもそも人間側が今の消費ペースを画面の外に置いていたら気づくのが遅れます。5時間ブロックの残量、7日枠の残量、コンテキスト使用率、セッション課金額 ―― これを毎ターン見えるところに出したい。

幸い、Claude Codeのsettings.jsonにstatusLine.commandを書くと、これらを含むJSONが毎ターンそのままシェルのstdinに流れてきます。認証もAPIコールも要りません。

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

このコマンドが標準出力に返した文字列がそのままステータスラインになります。あとは中身をどう料理するかだけの話です。

JSONの中身：欲しい値は全部stdinにある

statusline.sh冒頭のコメントが仕様書代わりになっています。

# Plan-limit % and resets come straight from Claude Code's statusline stdin
# (.rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}) — no auth,
# no endpoint call. Context % is .context_window.used_percentage (pre-calc).
# rate_limits is "only present for subscribers after first API response", so we
# fall back to "--" until the first turn lands. Costs: session = stdin
# .cost.total_cost_usd; today = ccusage daily (the only external call, cached).

実際の抽出はこれだけです。

MODEL=$(j '.model.display_name // .model.id // "claude"' | sed 's/claude-//')
EFFORT=$(j '.effort.level // empty')
FAST=$(j '.fast_mode // empty')
CWD=$(j '.workspace.current_dir // .cwd // ""' | sed "s|$HOME|~|")
SESSION_USD=$(j '.cost.total_cost_usd // 0')

CTX=$(j '.context_window.used_percentage // empty')
H5=$(j '.rate_limits.five_hour.used_percentage // empty')
H5R=$(j '.rate_limits.five_hour.resets_at // empty')
D7=$(j '.rate_limits.seven_day.used_percentage // empty')
D7R=$(j '.rate_limits.seven_day.resets_at // empty')

rate_limitsは「サブスクで最初のAPI応答が返ったあとにだけ現れる」ので、セッション開始直後は--表示にフォールバックします。ここで例外を投げたり空文字のまま%計算をしたりしないのがポイントで、pct()ヘルパーが空値を--に丸めます。

pct() { [ -n "$1" ] && printf '%.0f%%' "$1" || printf '%s' "--"; }

日次課金だけはccusageという外部コマンドが要る唯一の値です。ここは30分キャッシュ（/tmp/cc-daily-cache.json、AGE -lt 1800）にして、ロックディレクトリで多重起動を防ぎつつバックグラウンドで更新します。

find "${DAY_CACHE}.lock" -maxdepth 0 -mmin +5 -exec rmdir {} \; 2>/dev/null
[ "$NEED" = true ] && mkdir "${DAY_CACHE}.lock" 2>/dev/null && \
  ( "$CCUSAGE" daily --json --offline 2>/dev/null > "${DAY_CACHE}.tmp" \
    && mv "${DAY_CACHE}.tmp" "$DAY_CACHE"; rmdir "${DAY_CACHE}.lock" ) &

色を%で切り替える

3値（context% / 5h% / 7d%）はすべて同じpcolor()を通します。緑50%未満・黄50〜79%・赤80%以上の3段階だけの単純なしきい値です。

pcolor() { local n="${1%%.*}"; [ -z "$n" ] && { printf '%s' "$DIM"; return; }
  if [ "$n" -ge 80 ] 2>/dev/null; then printf '%s' "$RED"
  elif [ "$n" -ge 50 ] 2>/dev/null; then printf '%s' "$YEL"
  else printf '%s' "$GRN"; fi; }

小数点が入ってきても${1%%.*}で整数部だけ切り出してから-ge比較するので、jqが返す42.7のような値でも壊れません。3行の組み立てはこうなります。

L1=$(printf "${DIM}📁${R} ${CYAN}%s${R}%s%s" "$DIRNAME" "$BR" "$WT")
L2=$(printf "${MAG}🤖 %s%s${R}  ${DIM}·${R}  ${CTXC}🧠 ctx %s${R}  ${DIM}·${R}  ${C5}🕐 5h %s${R}%b  ${DIM}·${R}  ${C7}📅 7d %s${R}%b" \
  "$MODEL" "$EFF" "$(pct "$CTX")" "$(pct "$H5")" "$R5" "$(pct "$D7")" "$R7")
L3=$(printf "${DIM}💴 session${R} %s   ${DIM}今日${R} %s%b" \
  "$(yen "$SESSION_USD")" "$(yen "$DAY_USD")" "$PROJ_HEALTH_SEG")

printf "%b\n%b\n%b" "$L1" "$L2" "$L3"

📁 dir ⌥branch / 🤖 model ctx% 5h% 7d% / 💴 session ¥x 今日 ¥y <health> の3行構成です。

サブプロセスゼロ読み出し：78秒をキャッシュで消す

ここからが本題です。automation-health.shはlaunchd・hooks・skill-harvest・会話ログ・Obsidian連携までを横断チェックするスクリプトで、実際に時間を測ったらこうでした。

( bash ~/.claude/scripts/automation-health.sh > /tmp/ah-test-out.txt 2>&1; )
  4.43s user 7.81s system 15% cpu 1:18.23 total

78秒です。ステータスラインは毎ターン再描画されるので、これを同期で呼んだ瞬間に体感速度が死にます。だからstatusline.shはこの結果を5分キャッシュし、キャッシュが新しければファイルを1回catするだけで済ませます。

HEALTH_CACHE="/tmp/cc-health-cache"; HEALTH=""
if [ -f "$HEALTH_CACHE" ]; then
  HAGE=$(($(date +%s) - $(stat -f %m "$HEALTH_CACHE" 2>/dev/null || echo 0)))
  [ "$HAGE" -lt 300 ] && HEALTH=$(cat "$HEALTH_CACHE" 2>/dev/null)
fi
if [ -z "$HEALTH" ]; then
  ( h=$(~/.claude/scripts/automation-health.sh 2>&1 | grep -oE "ALL GREEN|WARN|FAIL" | head -1)
    case "$h" in
      "ALL GREEN") echo "🟢" > "$HEALTH_CACHE" ;;
      "WARN")      echo "🟡" > "$HEALTH_CACHE" ;;
      "FAIL")      echo "🔴" > "$HEALTH_CACHE" ;;
      *)           echo "⚫" > "$HEALTH_CACHE" ;;
    esac ) &
  HEALTH="·"
fi

キャッシュが5分以内ならstatだけで完了、期限切れならバックグラウンドで重い本体を起動して現在のターンは·（読み込み中）を出し、次のターン以降で🟢/🟡/🔴に置き換わります。同期で待たないのが肝で、統計的にはほぼ全ターンがキャッシュヒットになるので、体感コストは「ファイルのstat＋条件分岐」だけに収まります。

project-health.sh側はさらに段階を分けていて、4時間(14400秒)を超えたら1800秒スロットルの背景更新、25時間(90000秒)を超えたら経過時間つきで古さを表示、という2段構えです。

if [ "$PH_AGE" -gt 14400 ] && [ "$PH_AGE" -lt 90000 ]; then
  PH_RFILE="/tmp/cc-ph-bg-refresh-ts"
  PH_ROK=true
  if [ -f "$PH_RFILE" ]; then
    RLAG=$(($(date +%s) - $(stat -f %m "$PH_RFILE" 2>/dev/null || echo 0)))
    [ "$RLAG" -lt 1800 ] && PH_ROK=false
  fi
  [ "$PH_ROK" = true ] && { touch "$PH_RFILE"; ( ~/.claude/scripts/project-health.sh >/dev/null 2>&1 ) & }
fi

「重い処理を毎回呼ぶ」と「キャッシュを一生更新しない」の中間がこれです。キャッシュ期限切れを検知したターンは古い値のまま即返し、更新はバックグラウンドの子プロセスに投げて自分は待たない。ステータスラインのように「毎回同期で呼ばれるが遅延は許されない」場所では、この非同期リフレッシュがほぼ必須の型でした。

再利用できる最小版：claude-limits-segment.sh

statusline.shはプロジェクト固有の健全性表示まで抱えていて重いので、残量セグメントだけを他所（別のプロンプト表示やtmuxなど）に埋め込みたい時のために、同じキャッシュJSONを読むだけの51行の独立スクリプトも置いています。全文コピペで動きます。

#!/usr/bin/env bash
set -euo pipefail

STATUS_JSON="${CLAUDE_STATUSLINE_JSON:-/tmp/cc-statusline-last.json}"

if [ ! -s "$STATUS_JSON" ]; then
  printf '🕐 5h -- · 📅 7d --'
  exit 0
fi

age=$(( $(date +%s) - $(stat -f %m "$STATUS_JSON" 2>/dev/null || echo 0) ))

jq_field() {
  jq -r "$1 // empty" "$STATUS_JSON" 2>/dev/null
}

pct() {
  local v="$1"
  if [ -n "$v" ]; then
    printf '%.0f%%' "$v"
  else
    printf -- '--'
  fi
}

h5=$(jq_field '.rate_limits.five_hour.used_percentage')
h5r=$(jq_field '.rate_limits.five_hour.resets_at')
d7=$(jq_field '.rate_limits.seven_day.used_percentage')
d7r=$(jq_field '.rate_limits.seven_day.resets_at')

stale=''
[ "$age" -gt 600 ] && stale='*'

printf '🕐 5h %s' "$(pct "$h5")"
[ -n "$h5r" ] && printf ' ⏪%s' "$(date -r "$h5r" '+%H:%M' 2>/dev/null)"
printf ' · 📅 7d %s' "$(pct "$d7")"
[ -n "$d7r" ] && printf ' ⏪%s' "$(date -r "$d7r" '+%-m/%-d %H:%M' 2>/dev/null)"
printf '%s' "$stale"

statusline.shが/tmp/cc-statusline-last.jsonに毎ターン書き出している生JSONを、別プロセスから読むだけの設計です。age -gt 600（10分)で末尾に*を付けて「これは古いデータですよ」と警告するのが、実は本体のstatusline.shにはない気配りです（次の落とし穴で触れます）。

踏んだ落とし穴

• automation-health.shを同期で呼んだら78秒固まる → 5分キャッシュ＋バックグラウンド起動、当ターンは·を返す
• rate_limitsは初回API応答まで存在しない → 空値なら例外にせずpct()で--にフォールバック
• automation-health.sh自身が多重起動ガード（mkdirロック）を持つ → statusline側の裏起動とcron定期実行が衝突すると"別インスタンス稼働中のためスキップ"でexit 0になり、結果を拾えず⚫（不明）を5分キャッシュしてしまう
• stat -f %mはBSD/macOS専用構文 → Linuxに持っていくと|| echo 0のフォールバックが常に発動し、キャッシュの年齢計算が壊れて毎回“期限切れ”扱いになる（エラーは出ないので気づきにくい）
• 本体のstatusline.shはstdinが空でも黙って古いJSONにフォールバックし続け、鮮度警告がない → 小さい方のclaude-limits-segment.shだけがage -gt 600で*を出す。2本を比べて初めて非対称に気づいた

まとめ

• settings.jsonのstatusLine.commandに投げるJSONには、認証もAPI呼び出しもなしで残量・コンテキスト%・課金額が全部乗っている
• 色分けはpcolor()1関数、しきい値は緑50%未満・黄50〜79%・赤80%以上だけのシンプル設計
• **78秒かかる重いヘルスチェックは、5分キャッシュ＋バックグラウンド起動で「当ターンは古い値を即返す」**に倒すと、体感コストはファイルreadだけになる
• 同じキャッシュJSONを読むだけの小さいスクリプトを分離しておくと、他の場所への埋め込みや使い回しが効く
• 2本のスクリプトを比べると、片方にしかない鮮度警告のような非対称に気づける。同じデータを読む実装は複数書いて突き合わせるのが地味に効く

次回は、このキャッシュ層をもう一段掘り下げて、バックグラウンド更新が重なったときの競合をどう潰したかを書く予定です。

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍
• AI導入・自動化の相談と実装テンプレ7本の配布は 公式LINE から💬

皆さんの ❤️ やシェアが励みになります！