使用量の上限

ccam usageは、各アカウントが5時間と週間の上限をどれだけ使ったかを、それぞれの時間枠がリセットされるまでの時間とともに表示します。長い作業を始める前や、Claude Codeが上限に近いことを知らせたときに使い、どのアカウントに余裕が残っているかを確認します。ccam statuslineはClaude Code用のステータスラインのコマンドです。Claude Codeの中にアカウント名と使用量を表示し、その数値をccam usageのために保存します。

使い方

ccam usage                  # every account, once
ccam u                      # the same, shorter
ccam usage --watch          # redraw every 60 seconds until Ctrl+C
ccam usage --watch=10       # redraw every 10 seconds
ccam usage -v               # add per-model weekly limits and the data source
ccam usage --json           # machine-readable, one object per account
ccam usage --source cache   # saved numbers only, no network
ccam usage --refresh        # also renew expired logins of accounts not running
ccam statusline install     # set the status line in every account's settings.json

$ ccam usage
 Account     5-hour        Resets    Weekly        Resets    As of
 1 personal  ░░░░░░░░   0% -         ██████░░  70% 2d 16h    9h 36m ago (cached)
 2 work      ██░░░░░░  24% 2h 29m    ███░░░░░  41% 3d 11h    just now (cached)
 3 side      login expired, run `ccam side` once to refresh
→ Most headroom: personal   (open it with ccam next --auto)

ターミナルでは、各行にfetching…と表示された表がすぐに現れ、各アカウントの応答があるたびにその行が描き直されます。As ofは数値がどれだけ前のものかを示し、(cached)はエンドポイントではなく保存済みのファイルから取得した数値であることを意味します。最後の行は、5時間の使用量が100%未満で最も少ないアカウントを示し、アカウントが2つ以上ある場合だけ表示されます。ログインしていないアカウントにはnot logged in → ccam login <name>、APIキーのアカウントにはno limits (API)と表示されます。

ccam statusline installの後は、Claude Codeに[work] · Opus · 5h 24% · 7d 41%のような行が表示されます。

オプション

--sourceにそれ以外の値を指定すると、--source must be live or cacheで失敗します。ccam usageは引数を取りません。

ccam statuslineは、Claude Codeのステータスライン用のJSONを標準入力から読みます。オプションは--wrap <command>の1つだけで、既存のステータスラインのコマンドを指定すると、その出力の1行目の前にアカウント名が付きます。ccam statusline installはオプションを取りません。どちらも--dry-runを--dry-run is not supported by `ccam statusline`; nothing was changedで拒否します。

しくみ

数値の取得元は2つあります。各アカウント自身のログインで呼び出す、Anthropicの公開ドキュメントに記載されていない使用量エンドポイントGET https://api.anthropic.com/api/oauth/usageと、Claude Codeがステータスラインのコマンドに渡す値です。これらはすべてinternal/usageにあります。

1. cli.usageCmdがconfig.tomlを読み込み、アカウントごとに1つのusage.Accountを作ります。内容は、フォルダー~/.local/share/ccam/profiles/<name>/、セッションのフォルダー（実行中かどうかを確認するため）、その場所のままインポートしたかどうかです。
2. Fetcher.FetchAllがアカウントごとに1つのgoroutineを起動します。すべてが1つのhttp.Clientを共有するので、エンドポイントへの接続は再利用されます。接続には最大2秒、各アカウントには合計3秒かかってもかまいません。リダイレクトするとトークンが別の場所に再送されてしまうため、クライアントはリダイレクトをたどらず、応答は最大1 MBまでしか読みません。
3. 各アカウントの処理が終わるたびに、その行が描き直されます。失敗したアカウントや時間内に応答しなかったアカウントは保存済みの数値にフォールバックするので、1つの遅いアカウントがほかのアカウントを待たせることはありません。

各アカウントはそれぞれのgoroutineでエンドポイントに問い合わせ、タイムアウトしたアカウントは代わりに保存済みの数値を表示します。

personalとworkは時間内に応答し、最新の数値を表示します。sideは3秒より長くかかるので、fallback()が2つのキャッシュファイルを読み、最後に書き込まれたほうを使います。usage.Table()が行を描画し、usage.Best()が最後の行に示すアカウントを選びます。

1つのアカウントについて、Fetcher.Fetchは次の順序で確認します。

1. --source cacheの場合は、直接fallback()に進みます。
2. --no-cacheが指定されていなければ、~/.local/state/ccam/usage/<name>.jsonにある、取得してから60秒（CacheTTL）未満の最新の結果をそのまま返します。ccam usageを続けて2回実行しても、リクエストはアカウントごとに1回で済みます。
3. readCredentials()が.credentials.json（またはmacOSのキーチェーン）を変更せずに読み、claudeAiOauthキーだけをデコードします。サブスクリプションのログインがない場合はnot logged in、.claude.jsonにAPIキーがある場合はno limits (API)になります。
4. 期限切れのアクセストークンは使いません。--refreshがない場合、そのアカウントは期限切れの印を付けて保存済みの数値を表示します。
5. それ以外の場合、ccamはエンドポイントを呼び出します。401や403はログインの期限切れ、それ以外のステータスや読めない本文はエラーとして扱い、どちらの場合も保存済みの数値にフォールバックします。
6. 正常な応答は、計測した時刻とともに<name>.jsonに書き込まれます。

fallback()は<name>.jsonと<name>.statusline.jsonの両方を読み、新しいほうを使います。保存済みの数値を表示する前に、各時間枠のリセット時刻を確認します。数値の保存後にリセットされた時間枠は、古い割合がもう当てはまらないため0%と表示します。上の例でpersonalがリセット時刻なしで0%と表示されているのはこのためです。

エンドポイントの応答形式は2つあります。新しい形式にはlimits配列があり、session（5時間）、weekly_all、weekly_scoped（モデル別）の項目を含みます。古い形式にはfive_hour、seven_day、seven_day_opus、seven_day_sonnetのオブジェクトがあります。ParseLiveは両方を読みます。limits配列が優先され、それに含まれないものを古いオブジェクトで補います。上限がまったく含まれない本文は形式の変更として報告され、ccam doctorがそれを知らせます。

トークンの更新

リフレッシュトークンはローテーションします。更新すると新しいリフレッシュトークンが発行され、古いものは無効になります。同じアカウントでClaude Codeが実行中のときにccamがログインを更新すると、そのセッションはサインアウトされてしまいます。そのため、ccam usageはトークンを読むだけで、--refreshを付けない限り書き込みません。このオプションを付けると、Fetcher.refreshが次の処理を行います。

1. ccam importでその場所のまま登録したアカウントは拒否します。ccamの知らないところで通常のclaudeがそのログインを使っている可能性があるためです。
2. macOSのキーチェーンに保存されたログインは拒否します。
3. ロックファイル$XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock（その変数が設定されていない場合は~/.local/state/ccam/locks/の下）を取得し、2つのccamのプロセスが同じトークンを二重に更新しないようにします。
4. ロックを保持した状態で、アカウントのセッションが実行中なら拒否し、別のプロセスがすでにトークンを更新していればリクエストをスキップします。
5. リフレッシュトークンをトークンエンドポイントにPOSTし、新しいトークンをfsutil.AtomicWriteで.credentials.jsonに書き戻します。ファイル内のほかのキーはすべて残します。

ステータスラインの収集

Claude Codeはステータスラインのコマンドを実行し、JSONドキュメントをパイプで渡します。ccamはそこからモデル名とrate_limitsを読み取ります。

1. runStatuslineは、ccamがClaude Codeを起動するときに設定するCCAM_PROFILEからアカウントを特定します。ない場合は、CLAUDE_CONFIG_DIRをアカウントのフォルダーと照合します。
2. ParseStatusLineがrate_limits.five_hourとrate_limits.seven_dayを読み取ります。APIキーのアカウントや、セッションの最初の応答より前では、JSONにレート制限が含まれません。その場合は何も保存しません。
3. SaveStatusLineが~/.local/state/ccam/usage/<name>.statusline.jsonに書き込みます。エンドポイントが応答しないとき、ccam usageはこれを使います。
4. ccamは[name] · model · 5h N% · 7d N%を出力します。--wrapを付けた場合は、同じ入力でコマンドをsh -cで実行し、代わりに[name]に続けてコマンドの出力の1行目を表示します。

ラップしたコマンドの制限時間は2秒です。それを過ぎるとコマンドは終了させられ、行にはアカウント名だけが表示されるので、遅いコマンドがClaude Codeのステータスラインを止めることはありません。

ccam statusline installは、各アカウントのsettings.jsonにstatusLineを書き込みます。アカウントにすでにステータスラインのコマンドがある場合、ccamはそれを--wrap '<old command>'として残します。グループで共有されているsettings.jsonは、リンクを通じて1回だけ書き込まれるので、グループのすべてのアカウントに反映されます。もう一度実行すると、すでにccamを使っているファイルについては(already set)と表示します。

安全性と特殊なケース

• --refreshを付けない限り、ccam usageがトークンファイルを変更することはありません。ログインの期限が切れたときは、ccam <name>でそのアカウントを一度起動すれば、Claude Codeが更新します。
• --refreshは、実行中のアカウント、インポートしたアカウント、キーチェーンのログインには一切触れません。更新を拒否した場合は、保存済みの数値とその理由を表示します。
• 使用量エンドポイントは公開ドキュメントに記載されておらず、変更される可能性があります。変更された場合でも保存済みの数値は表示され、ccam doctorが形式の変更を報告します。
• 保存済みの数値も応答もない場合、その行にはlookup failed:と理由が表示されます。たとえば--source cacheではno saved usageとなります。
• キャッシュファイルに保存されるのは割合とリセット時刻だけで、トークンが保存されることはありません。

関連項目

• 使用量の上限とアカウントの切り替え
• 次のアカウントへの切り替え
• 使用量の上限に達したときのワークフロー
• コマンド