headroom

コーディングエージェントは、ジョブを開始する前に Claude と Codex の利用上限を確認します。

headroomd は、サブスクリプションで報告される5時間および週単位の利用上限を読み取り、CLI または MCP 経由で、続行、待機、または別の経路への切り替えを判断します。

npm install -g headroomd   # or: brew install apertur3/tap/headroom
headroom setup
headroom can claude-fable --owner me && echo go

次に、Claude Code プラグインをインストールします（上記の headroomd が必要です）。

claude plugin marketplace add Apertur3/headroom
claude plugin install headroom@headroom

macOS、Linux、Windows（実験段階）に対応しています。テレメトリーはありません。実行時の依存関係はありません。

headroomlabs-ai/headroom（コンテキスト圧縮プロジェクト）とは関係ありません。

インストール

Node 22.13 以降が必要です。npm パッケージは headroomd、Homebrew のフォーミュラは apertur3/tap/headroom です。どちらも headroom コマンドをインストールします。

npm install -g headroomd
# or, on macOS and Linux: brew install apertur3/tap/headroom
# finds your logins, runs the doctor, asks before each change
headroom setup
# one block per account: percent used, reset time and pace state per window
headroom

Claude の使用状況は、Claude Code のステータスラインから取得します。これを ~/.claude/settings.json（または 他の各プロファイルの settings.json）に追加するか、既存のステータスラインを headroom statusline --chain '<your command>' で連結してください。

{ "statusLine": { "type": "command", "command": "headroom statusline" } }

これに加えて、Headroom は Claude Code 独自の /usage を最大 10 分ごとに実行します（ステータスラインでは取得できないスコープ別の使用状況を追加します。ステータスラインは claude -p では 実行されないため、実行の合間に古い情報になることがあります）。headroom doctor と headroom status で、どちらが 使用中かを確認できます。Headroom が Claude の設定ファイルを編集することはありません。

Claude Code の場合、npm または Homebrew で headroomd をインストールした後、プラグインをインストールしてください。

claude plugin marketplace add Apertur3/headroom
claude plugin install headroom@headroom

プラグインには Headroom スキル、MCP サーバーの登録、各プロンプトに表示されるクォータ行が含まれています。 headroom hook install と併用しても、クォータ行が二重に表示されることはありません。 要件とアンインストールコマンドについては、Claude Code plugin を参照してください。

すでに Claude Code や別のエージェントを実行していますか？skills/headroom/SKILL.md をそのスキルディレクトリにコピーして、「set up headroom」と伝えてください。

プラグインを使わない場合、headroom setup により、デフォルトの Claude Code プロファイルに MCP サーバーを登録できます。手動で登録する場合、または別のプロファイルに登録する場合：

claude mcp add --scope user headroom -- headroom mcp
CLAUDE_CONFIG_DIR=~/.claude-work claude mcp add --scope user headroom -- headroom mcp

MCP に対応していないエージェント（たとえば Codex）は、CLI を呼び出します。その後、エージェントに For agents の手順を伝えてください。MCP ツールと呼び出し例については、 docs/mcp-and-agents.md を参照してください。

headroom accounts discover   # finds Claude, Codex, Antigravity, Grok and Kimi logins

headroom setup                # discovery, doctor, service, MCP registration -- asks before each change

エージェント向け

エージェントが読み込む CLAUDE.md または AGENTS.md にこれを貼り付け、プレースホルダーを独自のアクションクラス、メーター、エージェント名に置き換えてください。エージェントは、作業を割り当てる前に Headroom を確認するようになり、あなたに尋ねる必要がなくなります。

## Usage limits (Headroom)

Check Headroom before you start work on a subscription. Do not ask me about usage or reset times.

- `headroom can <class> --owner <your-name>`: exit 0 means go, exit 2 means no. Any other exit
  is an error: treat it as no. Classes are the `[consumes]` entries in `~/.headroom/routing.toml`.
- On no, try the next class in your fallback list. If none has room, run
  `headroom wait --meter <meter> --until-reset --max 6h` (exit 3 means it timed out), then run
  `headroom can` again before you start anything.
- Start a job with
  `headroom run --meter <meter> --need <window>:<points> --owner <your-name> -- <command>`,
  for example `--need 5h:10` for 10 percent of the 5-hour window. It reserves the points, runs
  the command and releases them when it exits. Exit 2 means refused; otherwise it returns the
  command's own exit code.
- UNKNOWN means there is no trustworthy reading. Treat it as no. Never pass `--allow-unknown`
  unless I ask for it.
- For the full picture, read `headroom --json`, not the human view.
- In Claude Code with the Headroom MCP server, `quota_can` answers the same question as
  `headroom can`.

各ターンでエージェントの前に現在のクォータを表示するには、headroom hook install --agent claude を実行するか（または headroom setup で「はい」と回答してください）、各 Claude Code プロンプトに、デーモンが最後にポーリングした際に書き込んだ1行が、その経過時間とともに含まれるようになります。1ターンあたり約60トークンを使用します。任意のエージェントで同じ行を表示するには、headroom line を実行してください。現時点では macOS および Linux 上の Claude Code のみが対象です。Windows、Codex、Gemini のフックにはまだ対応していません。

単純な can は参考情報です。予約すると、Headroom を利用する他のエージェントにポイントが確保されたことを知らせますが、ジョブ自体が消費するポイントを制限するものではなく、Headroom を利用しないツールを停止することもできません。ペース状態、リース、予約について詳しくは、skills/headroom/SKILL.md をご覧ください。

プラットフォームの対応状況と既知の制限事項

_{ソース：5つのサブスクリプションサービス（Claude、Codex、Kimi、実験的な Antigravity と Grok）と2種類のローカルサーバー（vLLM と llama.cpp）。読み取りデータが古い場合や読み取りに失敗した場合は、数値ではなく常に UNKNOWN と表示されます。詳細な説明 · 再現方法}

理由

複数のジョブに処理を振り分けるエージェントには、まず 2 つの答えが必要です。このアカウントでジョブを実行できるか、そして、ほかのどのジョブがすでに容量を予約しているかです。ベンダーの画面では、プログラムがこのどちらの答えも得られません。また、古い読み取り値を使うと、すでに容量がないアカウントにさらに作業を送ってしまう可能性があります。Headroom はベンダーの読み取り値と協調的な予約を組み合わせます。読み取り値が古い場合や失敗した場合は数値ではなく UNKNOWN を表示し、--allow-unknown を渡さない限り、can はその状態に対して NO を返します。

1 つのデーモンが Claude、Codex、Antigravity、Grok、Kimi、ローカルの vLLM または llama.cpp プール全体のクォータを読み取り、履歴を保持してリセットを検出します。Antigravity と Grok のサポートは実験的です。

_{合成データです。端末では、scripts/render-demo-animated.mjsで生成されたモックホームに対して、実際のCLIを実行しています。}

インストール  ·  エージェント向け  ·  理由  ·  デモ  ·  設計原則  ·  ドキュメント

使用量アナライザーとの違い

ccusageなどの使用量アナライザーは、ローカルの使用量ファイルを読み取り、推定コストを報告します。Headroomは、ベンダーが提供する使用量と上限を、ベンダー自身の使用量エンドポイントから読み取り、作業開始前に答えを返します。作業を割り振るエージェント向けに、can、gate、route、リース、受信箱を提供します。これらは異なる問いに答えるもので、併用できます。

使用前と使用後

確認せずにいると、エージェントはタスクの途中で上限に達し、それを知ることになります。Headroomを使えば、事前に確認し、答えが「いいえ」の場合はフォールバックリストの次のクラスを試します。canは確認のみを行います。複数のジョブを同時に開始する場合は、各ジョブが容量を予約するようheadroom runを使います。

Headroomなし

# weekly limit reached mid-task, work stops half done
codex exec "refactor the billing module"

Headroomあり

if headroom can codex-build --owner builder; then
  codex exec "refactor the billing module"
elif headroom can claude-fable --owner builder; then
  claude -p "refactor the billing module"
else
  # no class has room: wait for a reset, then check again before dispatching
  headroom wait --meter codex-main:main --until-reset --max 6h
fi

headroom run --meter ... --need ... --owner ... -- <command>はさらに一歩進んで、確認を行い、ジョブの実行時間中に容量を予約します。これにより、Headroomを使うほかのエージェントから、その容量は使用中に見えます。その後、コマンドを実行して予約を解放します。合成データを使った実行可能な例はexamples/にあります。

機能

ダッシュボード

_{合成データ。生成スクリプト：scripts/render-dashboard-demo.mjs。}

人間向けダッシュボードとブラウザーレポート

ターミナルの概要を開くか、ローカルのブラウザースナップショットをエクスポートします。

headroom dashboard
headroom dashboard --once --ascii

Tab キーでメーターを選択し、v で詳細を、e でイベントを表示します。どちらのグラフビューにも、記録された残容量が表示されます。読み取り値が欠落している場合や、信頼できない場合は空白になります。

同じ記録履歴をブラウザーで開くには、次のコマンドを実行します。

headroom dashboard --html report.html

生成されたファイルをブラウザーで開きます。レポートには、サブスクリプションの使用状況とリセット時刻の概要が表示され、ウィンドウグラフを選択したり、サンプルの詳細を確認したりできます。ライトテーマとダークテーマに対応しており、外部へのリクエストは行いません。これはスナップショットです。新しい読み取り値を反映するには、再生成してください。--force を指定しない限り、既存のファイルは保持されます。Unix のパーミッションに対応したシステムでは、新しいファイルのモードは 0600 になります。

設計原則

以下はすべて、コードで適用され、テストで保証されるルールです。それぞれに、実際に発生した過去の障害という理由があります。

• 安全側に倒す：偽の数値は出しません。 読み取り値が欠落、古い、または矛盾している場合は UNKNOWN になり、--allow-unknown を明示的に指定しない限り、can は NO を返します。
• 無効にできない、古いレーンのカナリア。 6 時間にわたって新しい読み取り値がないレーンは、通知設定の内容にかかわらずアラートを発します。
• Headroom が起動したと確実に証明できるものだけを終了します。 macOS と Linux では、記録された pid、コマンド、起動時刻が現在も一致する場合に限り、プロセスにシグナルを送ります。
• シークレットはそれぞれの保存先に保管します。 通知トークンは OS のシークレットストアに保存します。ベンダーの認証情報は使用時にベンダー独自のストアまたは認証情報ファイルから読み込み、コピーはしません。出力では機密情報を伏せます。
• 過去の障害ごとに、機密情報を伏せたフィクスチャを用意します。 現場で確認された Antigravity の障害パターンにはすべて、フィクスチャとテストがあります。

Headroom の仕組み

Headroom は、ネイティブの TypeScript アダプターを通じて Claude、Codex、Grok、Kimi の情報を読み取ります。 Antigravity は実験的な機能で、macOS 14 以降に対応しています。ログイン済みの agy と、稼働中の Headroom デーモンが必要です。npm および Homebrew パッケージには macOS ユニバーサルリーダーが含まれており、使用前に SHA-256 で検証されます。Gemini CLI はコンシューマー向けサブスクリプションでは不要であり、サポート対象外です。 Google は 2026 年 6 月 18 日に、コンシューマー向け Gemini CLI の利用を終了しました。

Antigravity のクォータについては、同梱の macOS リーダーがプロセス一覧から実行中の Antigravity 言語サーバー （デーモンが維持する agy）を見つけ、そのローカルポートと、プロセスにある場合は コマンドラインからローカル CSRF トークンを取得し、127.0.0.1 上のサーバーにクォータの 概要を問い合わせます。agy の OAuth 認証情報やセッション認証情報は読み取りません。デーモンはまた、 ログイン状態のマーカーのみを確認するため、~/.gemini/antigravity-cli/log にある agy の最新ログの末尾を読み取ります。Headroom は Gemini CLI の OAuth ファイルを読み取りません。 概要がない場合や取得に失敗した場合は、UNKNOWN のままです。実際の割合を含むアイドル状態のウィンドウでも、リセット時刻が人為的なものに見える場合は、疑義を示すマーカーが付くことがあります。成功したレスポンスに 5 時間のウィンドウがまったく含まれない場合（実際にアイドル状態のローリングウィンドウ）は、UNKNOWN ではなく n/a と表示され、予算チェックもブロックされません。エンドポイントの仕様とネイティブ リーダーは、CodexBar（MIT）を基にしています。

ジョブ開始前の予算チェック

この合成例では、使用率が 20% で、別の所有者が 75% を予約しています。残りの容量では 10 ポイントのジョブを実行できないため、子コマンドは開始されません。

$ headroom run --meter claude-main:all --need wk:10 --owner builder -- codex exec "Run the tests"
wk needs 10 more but only 0.0 left after 75.0% already leased before the 10% reserve

十分な容量がある場合、run は容量を予約してコマンドを開始し、完了時に予約を解放します。 チェックと予約はプロセス間でアトミックに行われます。単独の can または gate は助言的なものです。 作業開始時には run または can --lease を使用してください。これらの予約によって Headroom を 使うエージェント間の調整はできますが、サブスクリプションを消費する無関係なツールを停止することはできません。

例

合成データを使って実行でき、ログインは不要です。一度ビルドし、シード済みのホームディレクトリを CLI に指定してください。

npm run build
# sets HEADROOM_HOME to a throwaway demo home
eval "$(node scripts/demo-home.mjs)"
# walks a fallback list, dispatches on the first class with room
bash examples/orchestrator-loop.sh
# refuses a job the budget cannot cover (exit 1)
bash examples/ci-gate.sh
# the MCP call a client sends, over stdio
bash examples/mcp-quota-can.sh

スクリプトは HEADROOM_HOME がそのデモ用ホームディレクトリを指していないと実行を拒否するため、 実際の ~/.headroom に触れることはありません。また、グローバルな headroom ではなく、リポジトリの ビルド成果物（dist/cli.js）を呼び出します。使用するバイナリも表示します。

スクリプトと、スターター用の accounts.toml、policy.toml、routing.toml については examples/ を参照してください。

ドキュメント

• docs/claude-code-plugin.md：Claude Code プラグインのインストール、クォータ行、MCP、アンインストール
• docs/quickstart.md：インストールから実態を示す最初の行まで。macOS、Linux、Windows に対応
• docs/concepts.md：プリンシパル、メーター、ウィンドウ、観測値、ペース状態、リース、イベント
• docs/mcp-and-agents.md：MCP ツール、呼び出し例、オーケストレーターによる使用方法
• docs/json-contract.md：すべての --json 出力と MCP ツール結果の、バージョン管理されたフィールドごとの形式と互換性の保証
• docs/vendors.md：Headroom がベンダーごとに読み取る情報と、既知の実運用上の制限

比較と読み取り対象

Headroom はコストトラッカーではありません。ccusage はローカルログから支出を推定し、headroomd はベンダーが適用する上限を読み取ります。両者は併用できます。

Headroom は非公式です。デフォルトでは Claude Code 自体を通じて Claude の情報を読み取ります。それ以外のリーダーは、ユーザー自身のログイン情報を使って、文書化されていないベンダーのエンドポイントを利用します。ベンダーのエンドポイントとアカウントを参照してください。

ベンダーのエンドポイントとお使いのアカウント

_{独立したオープンソースプロジェクトであり、Anthropic、OpenAI、Google、xAI、Moonshot AI とは提携、後援、推奨の関係にありません。複数の連携機能では、お使いのログイン情報を使用して、ベンダーが公開していないエンドポイントにアクセスします。詳しくはベンダーのエンドポイントとお使いのアカウントをご覧ください。Claude、Codex、Antigravity、Grok、Kimi はそれぞれの所有者の商標であり、ここでは Headroom が読み取るサービスの名称としてのみ使用しています。これは npm パッケージの headroomd（リポジトリ Apertur3/headroom）であり、コンテキスト圧縮ライブラリ headroomlabs-ai/headroom など、Headroom という名称の他のプロジェクトとは関係ありません。}

一部のアダプターは、ベンダーが公開 API としてドキュメント化していない使用状況エンドポイントを読み取ります。Headroom は、同じマシンにインストールしてサインインしたベンダーの CLI から取得したお客様自身の認証情報を使って、使用状況の読み取りのみを行います。プロンプトは送信せず、アカウント設定も変更せず、他のツールの認証情報ストアに書き込むこともありません。ご自身が所有するアカウントでのみご利用ください。この種のアクセスはベンダーの利用規約で制限されている場合があり、ベンダーはいつでもエンドポイントを変更またはブロックできます。ご自身の責任でご利用ください。Headroom は、ブロックや制限を回避するために認証情報をローテーションしません。ご自身が所有するアカウントのみご利用ください。Headroom はベンダーの制限を回避する手助けはしません。

すべてのリクエストでは、headroomd/<version> として識別されます。デフォルト（claude_probe = false）では、トークンも非公開エンドポイントも不要です。Headroom はステータスラインのスナップショットを読み取るか、Claude Code 自身の /usage を実行し、Claude の Keychain 項目を読み取ることも Anthropic にアクセスすることもありません。claude_probe = true を設定すると、他の方法で読み取れない場合に限って、最後の手段として呼び出しを行います。この場合、Headroom は Claude Code の OAuth トークンを読み取り、ドキュメント化されていない Anthropic のエンドポイントを呼び出します。Anthropic の規約では、そのログイン情報は Claude Code の通常の使用に限るものとされています。

セキュリティ

Headroomはベンダーの認証情報や通知トークンをディスクに書き込まず、出力からシークレットを秘匿します。macOSでclaude_probe = trueを設定すると、同梱のヘルパーheadroom-claude-probeが/usr/bin/securityを実行してClaude CodeのKeychainトークンを読み取ります。この読み取りはKeychain項目自体のアクセスリストで許可されており、ヘルパーはトークンをメモリ内に保持して使用量のリクエストを自ら実行するため、トークンがNodeやHeadroomの出力に渡ることはありません。macOS 26.5上のClaude Code 2.1.263では、Keychainのダイアログは必要ありませんでした。ヘルパーはnpmパッケージ内にユニバーサルバイナリとして同梱され、使用のたびに記録済みのSHA-256と照合して検証されます。それ以外の場合、トークンはリクエスト時にベンダー独自の認証情報ファイルから読み取られ、リクエスト後に破棄されます。デーモンはmacOSおよびLinuxでは0600のローカルソケットで待ち受けます。Windowsでは名前付きパイプを使用し、双方がデーモンごとのセッショントークンを保持していることを証明します。このトークンはHEADROOM_HOME内の0600ファイルに保存されます。テレメトリーはありません。設定したベンダーと有効にした通知チャネルを除き、Headroomがユーザーの操作なしに行う唯一のリクエストは、上記の日次npmバージョン確認です。アカウントデータを含まない単純なGETリクエストであり、update_check = falseで無効にできます。headroom updateとheadroom engine installは、実行したときだけnpmとGitHubに接続します。エンジンはバージョンが固定され、チェックサムで検証されます。また、すべてのクエリが監査ログに記録されます。詳細はSECURITY.mdをご覧ください。

ステータス

リリースはnpmにheadroomdとして公開されます。CHANGELOG.mdには、各リリースでの変更点が記載されています。ベンダーのエンドポイントは非公開で、予告なく変更されるため、Headroomはエンドポイントを固定してフィクスチャを記録し、401、403、429ではバックオフし、古い数値の代わりにUNKNOWNを表示します。検証済みの内容と未検証の内容については、プラットフォームのサポートと既知の制限をご覧ください。AntigravityにはmacOSと、デーモンが保持するagyが必要です。ベンダーの設定をご覧ください。

貢献を歓迎します。CONTRIBUTING.mdと、good first issueラベルが付いたイシューをご覧ください。

MITライセンスです。サードパーティに関する通知はTHIRD_PARTY_NOTICES.mdをご覧ください。