Claude Code (Max plan) の使用率を tmux / Starship に表示する

3秒まとめ#

• Claude Code Max プランの5時間セッション使用率と週間使用率をカラーバーで表示
• tmux TPM プラグインと Starship カスタムモジュールの両方に対応
• OAuth トークンで使用率 API を叩き、キャッシュ付きで負荷を最小限に抑える設計

どんな人向けの記事？#

• Claude Code の Max プランを使っていて、残りの使用枠を常に把握したい方
• tmux や Starship でターミナル環境をカスタマイズしている方
• CLI 環境を自分好みにいじるのが好きな方

ステータスバーの右側に、Claude Code の使用率がカラーバーで表示されています。左のバーが5時間セッション使用率、右が週間使用率です。使用率に応じて緑→黄→赤と色が変わるので、パッと見で残りの枠が分かります。

背景：なぜ tmux に表示したいのか#

Claude Code を Max プランで使っていると、「今どれくらい使ったかな？」って気になりますよね。

/usage コマンドで確認できるけど、作業中にわざわざコマンドを打つのは面倒です。tmux のステータスバーに常時表示しておけば、コーディングしながらチラッと目をやるだけで使用状況が分かります。

仕組み#

ポイントは以下の3つです。

1. OAuth トークンで使用率 API を呼び出し: Claude Code が保持している OAuth トークンを使って、Anthropic の使用率 API からセッション/週間の利用率を取得
2. 5分間キャッシュ: API を毎回叩くのは無駄なので、取得結果を /tmp にキャッシュ。期限切れ時も古い値を即表示しつつバックグラウンドで更新
3. tmux カラーコード出力: スクリプトの stdout に #[fg=色] 形式の tmux フォーマットコードを含めることで、カラフルなバー表示を実現

インストール#

この仕組みを tmux TPM プラグインと Starship カスタムモジュールとして公開しました。

# プラグイン追加
set -g @plugin 'matsubo/claude-code-max-usage'

# status-right に組み込む
set -g status-right "#{claude_usage}"

# コンパクト表示: 22%/14%
set -g status-right "#{claude_usage_compact}"

[custom.claude]
command = "/path/to/claude-code-max-usage/scripts/claude_usage_starship.sh"
when = "test -f ~/.claude/.credentials.json"
format = "[$output]($style) "
style = ""
shell = ["bash", "--noprofile", "--norc"]

set -g @claude_usage_cache_ttl 600        # キャッシュ 10分
set -g @claude_usage_threshold_warn 40    # 黄色のしきい値
set -g @claude_usage_threshold_crit 70    # 赤のしきい値

技術的なポイント#

jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json

curl -s \
    -H "Authorization: Bearer $TOKEN" \
    -H "anthropic-beta: oauth-2025-04-20" \
    "https://api.anthropic.com/api/oauth/usage"

{
  "five_hour": {
    "utilization": 22,
    "resets_at": "2026-03-02T15:00:00Z"
  },
  "seven_day": {
    "utilization": 14,
    "resets_at": "2026-03-08T00:00:00Z"
  }
}

# 使用率 50% 未満は緑、80% 未満は黄、それ以上は赤
printf "#[fg=#a6da95]██#[fg=#7a839e]░░░#[fg=#a6da95]22%%"

キャッシュ戦略#

API を毎回叩くとレートリミットに引っかかる可能性があるので、5分間のキャッシュを設けています。

ポイントは、キャッシュ期限切れでも古い値を即座に返すこと。バックグラウンドで更新するので、ユーザーは待たされません。mkdir によるロックで二重実行も防止しています。

set -g status-right "#{?#{e|>=:#{client_width},120},<フル表示>,<コンパクト表示>}"

依存ツール#

• jq: JSON パース
• cURL: API リクエスト
• Nerd Font: アイコン表示（オプション）

まとめ#

Claude Code の使用率を tmux や Starship に表示することで、コーディング中でも残りの枠を意識できるようになりました。特に Max プランでは5時間ウィンドウの制限があるので、「あとどれくらい使えるか」がチラ見で分かるのはめちゃくちゃ便利です。

TPM プラグインとして公開したので、set -g @plugin の1行で導入できます。Starship ユーザーもカスタムモジュールとしてすぐに使えます。カラーパレットやしきい値も変更できるので、好みに合わせていじってみてください。

おまけ#