statuslineでspend_limitを表示する — Claude apps gatewayの支出上限を確認

Claude Code v2.1.251以降のstatuslineは、rate_limitsオブジェクトにspend_limitという項目を追加で運びます。個人のPro/Maxプランが使うfive_hour・seven_dayとは別物で、Claude apps gatewayを経由し、かつ管理者がその開発者向けに支出上限を設定しているときだけ現れるフィールドです。消化率とリセット時刻を、自作のstatuslineへ常時流し込めます。

rate_limits.spend_limitが運ぶ情報

spend_limitはused_percentageとresets_atの2つのキーを持ちます。used_percentageは0から100のパーセンテージで、上限を超えると100を上回ります。resets_atはUnixエポック秒で、上限の期間(日次・週次・月次)がリセットされる時刻を示します。ドル金額そのものは含まれません。

この2つのキーはfive_hour・seven_dayと形が同じなので、既存のstatuslineスクリプトに1行足すだけで拡張できます。ただし中身が指す対象は違います。five_hour・seven_dayはClaude.aiのサブスクリプションが持つレート制限で、spend_limitはgatewayの運用者がAdmin APIで設定した金額ベースの上限です。「spend limit」という呼び方はClaude Codeまわりで複数の仕組みに使われており、個人のPro/Max向けの支出上限や組織のAdmin settings側の支出上限とは別の概念です。呼び分けの全体像は「Could not update spend limit」の対処の一覧が詳しく、本記事が扱うのはそのうちgateway経由の1系統だけです。

表示までに満たす前提条件

spend_limitが出るには3つの条件が同時に必要です。ひとつでも欠けるとフィールドごと現れません。

1. Claude apps gatewayを経由してリクエストを送っていること
2. 管理者がAdmin APIであなた個人(またはあなたが属するIdPグループ・組織)に支出上限を設定していること。設定手順はClaude apps gatewayで開発者ごとの支出上限を設定するにあります
3. 開発者マシン側のClaude Codeがv2.1.251以降であること

3つ目には注意が必要です。gatewayサーバー側はv2.1.225以降であれば十分で、v2.1.251まで上げる必要はありません。上げるべきなのは開発者の手元のClaude Codeで、バージョンを混同すると「サーバーは新しいのにフィールドが出ない」という状態になります。手元のバージョンはclaude --versionで確認できます。

自分でgatewayへ明示的に切り替えた記憶がなくても、この条件を満たしていることがあります。組織が配布した環境設定で最初からgateway経由になっているケースが多く、spend_limitが出るかどうか自体が、自分のセッションがgateway経由かを確かめる手がかりにもなります。

claude --version

rate_limitsオブジェクト自体、セッション内で最初のAPIレスポンスが返るまでは現れません。起動直後のstatuslineに何も出なくても、故障ではなくこの仕様どおりの挙動です。

spend_limitを含むstatuslineスクリプトを書く

公式ドキュメントが示すサンプルスクリプトはfive_hour・seven_dayのみを扱い、spend_limitには触れていません。既存のスクリプトへ次のように1系統足すと、3つのウィンドウをまとめて表示できます。

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
SPEND=$(echo "$input" | jq -r '.rate_limits.spend_limit.used_percentage // empty')
 
LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"
 
if [ -n "$SPEND" ]; then
  SPEND_INT=$(printf '%.0f' "$SPEND")
  RESET='\033[0m'
  if [ "$SPEND_INT" -ge 95 ]; then COLOR='\033[31m'
  elif [ "$SPEND_INT" -ge 75 ]; then COLOR='\033[33m'
  else COLOR=''
  fi
  LIMITS="${LIMITS:+$LIMITS }${COLOR}spend: ${SPEND_INT}%${RESET}"
fi
 
[ -n "$LIMITS" ] && echo -e "[$MODEL] | $LIMITS" || echo "[$MODEL]"

75%・95%というしきい値は、Claude Code自身がgatewayの上限接近時に出す警告と同じ基準です。統一しておくと、statuslineの色とCLIの警告メッセージが同じタイミングで揃います。printf '%.0f'で整数化しているのは、100を超えた値をそのまま比較するとbcのような外部コマンドが要るため、整数比較で済ませる方が依存が少なく済むからです。

five_hour・seven_dayと混在させるときの注意

gateway経由のセッションはAPIキー認証が前提になることが多く、Claude.aiのサブスクリプション認証が使うfive_hour・seven_dayは同じセッションに出ないことがあります。逆にPro/Maxで直接ログインしているセッションでは、gatewayを経由しない限りspend_limitは出ません。3つのウィンドウはそれぞれ独立に不在になり得るため、rate_limitsが存在するからといって3つとも揃うとは限りません。

もうひとつ見落としやすい挙動があります。Claude Codeは各ウィンドウのresets_atが過ぎると、そのウィンドウを個別に表示から落とします。しばらく前まで出ていたspendの数値が消えたときは、故障ではなく期間がリセットされて新しい計測が始まる前の一瞬という可能性が高いです。スクリプト側は// emptyで不在を吸収する書き方を徹底し、特定のウィンドウが常に存在する前提でパースしないことが安定運用の分かれ目になります。

resets_atを読める時刻に変換する

resets_atはUnixエポック秒のままでは読みにくいので、dateコマンドで人間が読める形式に変換します。Linuxのdate -dとmacOSのdate -rは書式が違うため、両対応にするなら片方が失敗したらもう片方を試す形にします。

resets_at=$(echo "$input" | jq -r '.rate_limits.spend_limit.resets_at // empty')
if [ -n "$resets_at" ]; then
  reset_str=$(date -d "@$resets_at" '+%m/%d %H:%M' 2>/dev/null || date -r "$resets_at" '+%m/%d %H:%M' 2>/dev/null)
  echo "spend resets: $reset_str"
fi

gatewayのキャップはUTCの暦境界でリセットされる仕様で、日次は毎日00:00 UTC、週次は月曜、月次は1日と決まっています。そのためresets_atの値だけで周期を判別できます。変換した時刻が翌日の00:00 UTCなら日次、次の月曜なら週次、翌月1日なら月次です。運用者からの周期共有を待たなくても、statusline側でこの判定ロジックを組めます。月次の上限は数値の変化がゆるやかなので日付までの表示で足り、日次の上限は残り時間まで出したほうが実用的です。

自動警告・/usage・statuslineの3つを使い分ける

gatewayの支出上限は、Claude Codeの中で3つの異なる面に表示されます。それぞれ必要なバージョンと更新頻度が違うので、どれか1つだけを見ていると気づくタイミングがずれます。

自動警告はしきい値を跨いだ瞬間にしか出ないため、普段の消化ペースをつかむ用途には向きません。/usageは/usageコマンド自体の見方がClaude Codeの/usageコマンドで見る使用量の内訳にまとまっていて、狙ったタイミングで開いて確認するのに向きます。statuslineは常時表示できる代わりに、実装と保守の手間が読者側に残ります。ペースをこまめに把握したい開発者はstatusline、しきい値超過だけ知れれば十分な開発者は自動警告に任せる、という住み分けが妥当です。

gatewayを共有するチームでは、各自が消費ペースを日常的に把握しているほど、上限到達直前になってから慌てて引き上げを申請する事態を避けやすくなります。個人の対話セッションだけを気にする開発者と、複数セッションを並行で回す開発者とでは、statuslineの優先度も変わります。

よくあるつまずき

spend_limitがstatuslineに出ないときは、次の順に確認します。まずClaude apps gatewayを経由しているか。経由していなければAPIキーが直接Anthropicやクラウドプロバイダーに向いており、spend_limitという概念自体が存在しません。次に管理者があなた個人の上限を設定しているか。gatewayを使っていても、組織の共有請求だけで個人の上限を設定していない開発者にはこのフィールドが出ません。最後に手元のClaude Codeのバージョンです。claude --versionで確認し、v2.1.251未満なら、gatewayサーバーがどれだけ新しくても表示側が対応していません。

jqのクエリを.rate_limits.spend_limit.used_percentageと書くべきところを.rate_limits.used_percentageのように1階層省略すると、常にnullになりスクリプトが空文字を返し続けます。rate_limitsはfive_hour・seven_day・spend_limitという3つの子オブジェクトを持つ構造なので、階層を飛ばさずに指定します。

整数化を忘れて$SPENDを直接-geに渡す書き方も失敗しやすいところです。used_percentageは62.8のような小数を返すため、[ "$SPEND" -ge 75 ]はbashが「整数として扱えない」というエラーを出して比較自体が動きません。printf '%.0f'で整数化してから比較する順序を守ります。

spend_limitは3条件が揃わないと出現しないため、gateway環境を持たない開発者はスクリプトを実機で確認できません。公式ドキュメントが挙げる擬似入力の手法で、標準入力にJSONを直接流し込めばgateway無しでも検証できます。

echo '{"model":{"display_name":"Opus"},"rate_limits":{"spend_limit":{"used_percentage":62.8,"resets_at":1740787200}}}' | ~/.claude/statusline.sh

used_percentageに100を超える値(例: 142.3)を渡しても表示が丸められずそのまま出ることまで確認しておくと、超過表示だけがそのケースで壊れて出荷される事故を防げます。

よくある質問

個人のPro/Maxプランでもspend_limitは出ますか

出ません。個人のPro/Maxプランが持つレート制限はfive_hour・seven_dayで表現されます。月間の支出上限そのものはCLI内のプロンプトから変更します。Could not update your spend limitはその変更操作が拒否されたときの表示で、上限に達したこと自体を知らせるメッセージではありません。spend_limitはgateway経由の開発者向け上限専用のフィールドです。

Claude DesktopやWebのclaude.aiでも同じ数値を見られますか

見られません。statuslineはClaude Code CLIのsettings.jsonにあるstatusLine設定が描画する、ターミナル専用の表示面です。Desktop・claude.aiにはこの表示面自体が無いため、CLI以外で消化率を追いたい場合は、CLIから/usageを実行するか、gatewayの管理者に確認する形になります。

まとめ

rate_limits.spend_limitは、Claude apps gatewayの支出上限をstatuslineへ引き込むためのフィールドです。gateway経由であること、管理者があなた個人の上限を設定していること、手元のClaude Codeがv2.1.251以降であることの3条件が揃って初めて現れます。five_hour・seven_dayと同じ形の子オブジェクトなので、既存のstatuslineスクリプトへの追加は数行で済みます。100%を超えても丸めない、ウィンドウごとの不在を// emptyで吸収する、この2点を押さえれば、自動警告や/usageより細かい粒度で支出のペースを追えるようになります。statuslineが映すのはCLIの中だけで、Desktop・claude.aiには同じ表示面が無い点も、あわせて覚えておくと迷いません。