Claude Code の下に使用量と残量を常時表示する (statusLine + ccusage)

Claude Code を叩いていると気になる「あと何分？」

Claude Code を 1 日中叩いていると、「今日あとどれくらい Opus 使えるんだっけ」 が定期的に気になります。Claude Pro / Max / Team は 5 時間ブロックと 7 日間のレートリミットがあるので、調子よく書かせていたら急に止められる、というのがわりとストレスなんですよね。

/status を叩けば残量は見られるのですが、毎回打つのはだるい。ターミナルの下に常時出しておければ十分というわけで、statusLine 機能で下部バーを作り込んだら思った以上に便利だったので、設定を段階的に紹介します。

最終的にはこんな感じの表示になります。

statusLine って何

Claude Code には 任意のシェルコマンドの出力を下部 1 行に表示する機能 (statusLine) があります。~/.claude/settings.json に 1 ブロック書くだけで、Claude Code が毎メッセージ後にそのコマンドを叩いて、stdout をそのまま下部バーとして描画してくれます。

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

ポイントは、stdin に現在のセッション状態を表す JSON が流し込まれる ところです。この JSON には model.display_name や context_window.used_percentage、そして Pro / Max / Team プラン限定で rate_limits.five_hour / rate_limits.seven_day が入っていて、ここをそのまま読めば残量が取れます。

主なフィールドはこのあたりです (公式ドキュメントより抜粋)。

フィールド	中身
model.display_name	現在のモデル名 (例: Opus 4.7 (1M context))
context_window.used_percentage	コンテキスト使用率 (0〜100)
rate_limits.five_hour.used_percentage	5 時間ブロックの消費率 (Pro/Max/Team 限定)
rate_limits.five_hour.resets_at	5 時間ブロックのリセット時刻 (Unix epoch 秒)
rate_limits.seven_day.used_percentage	7 日間の消費率
rate_limits.seven_day.resets_at	7 日間のリセット時刻
cost.total_cost_usd	現在セッションの累計コスト (API 利用時)
workspace.current_dir	作業ディレクトリ

rate_limits は 初回 API レスポンスを受け取るまでは出てこない 点と、プランによっては seven_day が無い 点だけ気をつければ、あとは jq でどう加工するかだけの話です。

まずは jq ワンライナーで最小構成

最短で動かすならシェルスクリプト不要で、command に jq を直接書くだけで済みます。

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] ctx:\\(.context_window.used_percentage // 0)%\"'"
  }
}

これだけで [Opus 4.7 (1M context)] ctx:12% みたいな行が下に出ます。// 0 は used_percentage がまだ null のタイミングで落ちないようにする保険です。

Claude Code を再起動すれば反映されます。動いた時点でひとまず勝ちで、ここから欲しい情報を足していく形がやりやすいです。

5時間 / 7日のレートリミットも出す

jq ワンライナーだと分岐が書きにくくなるので、素直にシェルスクリプトにします。~/.claude/statusline.sh にこんな感じで置いて chmod +x しておきます。

#!/usr/bin/env bash
# ~/.claude/statusline.sh
input=$(cat)

model=$(echo "$input" | jq -r '.model.display_name // "?"')
ctx=$(echo "$input" | jq -r '(.context_window.used_percentage // 0) | floor')
cwd=$(echo "$input" | jq -r '.workspace.current_dir // ""' | sed "s|$HOME|~|")

now=$(date +%s)

bar() {
  local pct=$1
  local filled=$((pct * 6 / 100))
  local empty=$((6 - filled))
  local out=""
  for _ in $(seq 1 $filled); do out+="▓"; done
  for _ in $(seq 1 $empty);  do out+="░"; done
  printf "%s" "$out"
}

human() {
  local s=$1
  local d=$((s / 86400))
  local h=$(((s % 86400) / 3600))
  local m=$(((s % 3600) / 60))
  if   [ "$d" -gt 0 ]; then echo "${d}d${h}h"
  elif [ "$h" -gt 0 ]; then echo "${h}h${m}m"
  else echo "${m}m"
  fi
}

rate_part=""
for win in five_hour seven_day; do
  pct=$(echo "$input" | jq -r ".rate_limits.${win}.used_percentage // empty")
  rst=$(echo "$input" | jq -r ".rate_limits.${win}.resets_at // empty")
  [ -z "$pct" ] && continue
  pct=${pct%.*}
  label=$([ "$win" = "five_hour" ] && echo "5h" || echo "7d")
  [ -n "$rate_part" ] && rate_part+="  "
  rate_part+="${label} $(bar $pct) ${pct}% $(human $((rst - now)))"
done

if [ -n "$rate_part" ]; then
  echo "${model} | ctx:${ctx}% | ${rate_part} | ${cwd}"
else
  echo "${model} | ctx:${ctx}% | ${cwd}"
fi

やっていることはシンプルで、stdin の JSON を jq で分解して、プログレスバー (▓░) とリセットまでの残り時間を文字列化しているだけです。rate_limits が存在しない状態 (プラン外 / 初回応答前) は自動でその部分だけ抜け落ちます。

ローカルで挙動を試したいときは、モック JSON を流し込めば単体でデバッグできます。

echo '{"model":{"display_name":"Opus 4.7"},"context_window":{"used_percentage":12},"workspace":{"current_dir":"/home/you"}}' | ~/.claude/statusline.sh

ccusage を使うとコスト側が強い

自作スクリプトはレートリミット残量を見たいときに手っ取り早いのですが、1 日あたりのコスト・消費レート ($/hr)・セッション合計・モデル別内訳 あたりまで欲しくなったら ccusage に寄せるのが早いです。

ccusage には statusline サブコマンド (Beta) が入っていて、bunx か npx から呼ぶだけで下部バーを埋めてくれます。

{
  "statusLine": {
    "type": "command",
    "command": "bunx ccusage statusline",
    "padding": 0
  }
}

npx 派なら npx -y ccusage@latest statusline でもOK。

出力例は公式ドキュメント (ccusage.com/guide/statusline) にあるものを借りるとこんな形です。

🤖 Opus | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)

セッションコスト・本日のコスト・5 時間ブロック内のコストと残り時間・時間あたりの消費レート・コンテキスト使用トークン数、が一気に出ます。--visual-burn-rate emoji で消費レートを絵文字化したり、--cost-source both で ccusage 集計と Claude Code 側の集計を両方並べたり、ちょっとしたカスタマイズも可能です。

自作スクリプトと どっちか一方で良いというよりは、見たい軸が違うので両方を切り替えて使うくらいの温度感が近いと思います。コストを気にしたい週は ccusage、残り時間だけ気にしたい週は自作側、みたいに。

statusLine で他にもできること

せっかく statusLine を作り込むなら、使用量以外にも情報を載せられます。実際に試して便利だったのはこのあたりです。

• /statusline スラッシュコマンドに書いてもらう : Claude Code 自身にスクリプトを生成させられます。「モデル名とコンテキスト使用率をプログレスバーで出して」と自然言語で頼むと、~/.claude/ に出力ファイルを作って settings.json まで更新してくれます。叩き台としてとても助かります。
• git ブランチ / worktree 名 : workspace.git_worktree や worktree.name が stdin JSON に入っているので、複数 worktree を切り替えて作業しているときに現在地が一目で分かります。
• サブエージェント中かどうか : agent.name にサブエージェント名が入るので、「今このターンはサブエージェントに委譲している」のを視覚化できます。
• Vim モード : vim.mode も取れるので、NORMAL / INSERT を色付けすると操作ミスが減ります。
• output_style の表示 : output_style.name で今の出力スタイルが見えるので、切り替え忘れに気付きやすくなります。

フィールド単位で「気になるものは下に貼っておく」という使い方が合っていて、ダッシュボードを別タブで開く必要がなくなるのがありがたいです。

まとめ

• Claude Code の statusLine は、stdin JSON を jq で加工するだけで下部バーを自作できる
• rate_limits.five_hour / rate_limits.seven_day を読めば、5 時間と 7 日の残量が自前で出せる
• コスト系の情報がまとめて欲しいなら ccusage の statusline サブコマンドが速い
• /statusline で Claude Code 自身に書かせる手もある

残量が見えるだけで、今日この後どこまで進めるか の感覚が変わります。Claude Code をヘビーに使っている人ほど、設定を詰める価値は大きいです。

参照リンク

• Claude Code: Customize your status line (公式)
• ryoppippi/ccusage (GitHub)
• ccusage: Statusline Integration (公式ガイド)
• Bun