はじめに
Claude Code を使っていて、こんな経験はありませんか？
- 作業が乗ってきたところで、週間リミットに達して手が止まる
-
/usageを何度も打っては、「このペースで週末まで持つのか？」と暗算している - Fable などのモデル別の上限だけ先に尽きていたことに、あとから気づく
/usage を打てば今の使用率は分かります。ですが本当に知りたいのは、このままのペースで使ったら、いつ尽きるのかです。
そこで、上限の状況を macOS のデスクトップウィジェットとメニューバーに常時表示するアプリ「Orbit for Claude Code」を作りました。無料・MIT ライセンスで GitHub に公開しています。
この記事では、何ができるかと、裏側でどうやって情報を取っているかを紹介します。
作ったきっかけや開発の経緯は note に書いています。
非公式アプリです。 Anthropic とは無関係です。Claude Code がキーチェーンに保存している OAuth トークンを使い、/usage と同じ非公開エンドポイントを呼んでいます。エンドポイントの仕様は予告なく変わる可能性があります。
何ができるか
| ウィジェット | 表示内容 |
|---|---|
| Usage | 5 時間枠、週間枠、モデル別の週間上限、ペースマーカー、上限切れの予測 |
| Sessions | 実行中の Claude Code セッションの状態ランプ（作業中／入力待ち／待機）、コンテキストウィンドウの使用量 |
| Cowork | デスクトップアプリの最近の Cowork セッション |
| Claude status | status.claude.com の稼働状況と障害情報 |
| Today | 今日のトークン量、メッセージ数、API 換算コスト（ローカルログから集計） |
デザインは Glass Orbit（Liquid Glass のリング）、Pace Bars（カプセルバー）、Console（ターミナル風）の 3 種類です。英語・日本語・簡体字中国語・韓国語に対応しています。
一番の売り：「このペースだといつ尽きるか」
見出しには数字を並べる代わりに、このペースで使い続けたら、どの上限がいつ尽きるかを表示します。
このペースだと 土 05:00 ごろ 週の上限5h上限に到達 — 11:30 に回復余裕あり — 月 10:00 まで持ちます
残り 1 日を切ると赤、それより先ならオレンジで表示します。
インストール
macOS 26 以降と、Claude Code CLI にログイン済みの Pro / Max プランが必要です。
brew tap akito8639/tap
brew trust akito8639/tap
brew install --cask orbit-for-claude-code
起動後、ウィジェットギャラリーから好きなウィジェットを追加するだけです。アップデートはアプリ内（Sparkle）でも brew upgrade でも入ります。
仕組み
1. 使用量の取得
Claude Code はログイン情報を macOS のキーチェーンに Claude Code-credentials という名前で保存しています（環境によっては ~/.claude/.credentials.json）。中身は JSON で、claudeAiOauth.accessToken に OAuth のアクセストークンが入っています。
このトークンで次のエンドポイントを呼ぶと、/usage と同じ情報が返ってきます。
GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <accessToken>
anthropic-beta: oauth-2025-04-20
レスポンスの limits 配列に、各上限が次のような形で入っています（一部抜粋）。
{
"limits": [
{ "kind": "session", "percent": 15, "resets_at": "..." },
{ "kind": "weekly_all", "percent": 85, "resets_at": "..." },
{ "kind": "weekly_scoped", "percent": 81, "resets_at": "...",
"scope": { "model": { "display_name": "Fable" } },
"severity": "warning" }
]
}
session が 5 時間枠、weekly_all が全モデル共通の週間枠、weekly_scoped がモデル別の週間上限です。severity は Anthropic 側の警告レベルで、アプリ側の判定より深刻な場合はそちらを優先して色を付けています。
アクセストークンの期限が切れていたら、リフレッシュトークンで更新してキーチェーンの同じ項目に書き戻します。リフレッシュトークンは使うたびに新しいものに入れ替わるので、書き戻さないと Claude Code 側が古いトークンを持ったままになってしまいます。
2. ペースマーカー
各上限には、リセットまでの期間のうちどれだけ時間が経ったかを示す白い目盛り（ペースマーカー）を描いています。
/// 枠の経過割合（0...1）＝「このペースなら妥当」な使用率
func paceFraction(at now: Date) -> Double? {
guard let resetsAt else { return nil }
let start = resetsAt.addingTimeInterval(-kind.duration)
return min(max(now.timeIntervalSince(start) / kind.duration, 0), 1)
}
週の半分が過ぎて使用率 50% ならちょうど目盛りの位置です。使用率が目盛りより 10 ポイント以上先に進むとオレンジ（ペース超過）、25 ポイント以上なら赤で表示します。
3. 上限切れの予測
予測は単純で、これまでの平均ペースがこのまま続くと仮定して、100% に届く時刻を出しています。
/// 今までの平均レートを延長して 100% に届く時刻
func projectedExhaustion(at now: Date) -> Date? {
guard let resetsAt, resetsAt > now,
let f = paceFraction(at: now), f >= 0.12, // 枠の序盤は判断材料が少ない
utilization >= 3 else { return nil }
let start = resetsAt.addingTimeInterval(-kind.duration)
return start.addingTimeInterval(now.timeIntervalSince(start) * 100 / utilization)
}
これをすべての上限について計算し、一番早く尽きるものを見出しにします。ただし、次の工夫を入れています。
- リセット直前の上限切れは無視する。 週間枠ならリセットの 3 時間前以内、5 時間枠なら 20 分前以内に尽きる予測は、実質ほとんど影響がないので警告しません。
- 枠の序盤は予測しない。 経過が 12% 未満、使用率が 3% 未満のうちは、見出しを通常のペース判定（「順調」「ペース超過」）に戻します。
- モデル別の上限を使い切ったときは外す。 Fable の週間上限が 100% になっても、他のモデルはまだ使えます。その行は赤く表示し、見出しでは「まだ使える枠がいつまで持つか」を示します。5 時間枠と全モデルの週間枠は、尽きると何も使えないので「いつ回復するか」を表示し続けます。
- 時刻は丸める。 予測なので分単位の精度は不要です。1 時間単位（2 時間以内なら 10 分単位）で表示しています。
4. 実行中のセッション
Claude Code は実行中のセッションごとに ~/.claude/sessions/*.json を作ります。中には pid、cwd、status（busy / waiting / idle）、waitingFor などが入っています。デスクトップアプリの状態表示も同じファイルを元にしているようです。
Orbit はこのディレクトリを 20 秒ごとに読み、kill(pid, 0) でプロセスが生きているものだけを表示しています。
コンテキストウィンドウの使用量は、会話ログ ~/.claude/projects/<cwd をエンコードしたもの>/<sessionId>.jsonl の末尾 512KB だけを読み、最後の assistant 応答の usage から input_tokens + cache_read_input_tokens を出しています。ログは長くなるので、全部を読まないようにしています。
5. ウィジェットの更新
WidgetKit のウィジェットは、頻繁にリロードすると OS に制限されます。そこで次のようにしています。
- データの取得はメインアプリ側で行い、App Group の共有コンテナに JSON で保存する
- ウィジェットは保存された JSON を描画するだけにする
- 表示内容が実際に変わったときだけリロードする（最短 30 秒間隔にまとめる）
- 「◯分前」の表示がずれないよう、変化がなくても 45 分に 1 回は再描画する
おわりに
/usage を打つ回数が減り、「今週はもう少し飛ばしても大丈夫」「今日は Sonnet に切り替えよう」といった判断がすぐできるようになりました。
Claude Code を毎日使っている方はぜひ試してみてください。予測ロジックへの意見や不具合報告は GitHub の Issue でお待ちしています。