ドキュメント
インストールから内部設計まで、
1 ページで。
導入方法、メニューバー 5 タブ(Active / Usage / History / Update / Diag)と Graph ウィンドウの使い方、軽くあるための機構、プライバシー、FAQ。CodexBar の問題点と対比はにまとめています。
01 · インストール
インストール
GitHub Releases の DMG が推奨です。Developer ID で署名し、Apple のノータリゼーションを通しています。ソースからビルドしても同じものが動きます。
- macOS
- 14(Sonoma)以降。Apple Silicon / Intel 両対応(universal binary)
- ソースビルド時
- Xcode 16 / Swift 6(コマンドラインツールのみでは不足します)
- 依存パッケージ
- なし(SwiftPM のみ)
DMG ダウンロード
推奨Releases から AgentBar-<version>.dmg をダウンロードし、DMG を開いて AgentBar.app を Applications へドラッグします。起動するとメニューバーと Dock の両方に常駐します。
ソースからビルド
利用可能リポジトリをクローンして swift run。ビルドには Xcode 16 以降の Swift 6 ツールチェーンが必要です(CI は macOS 15 ランナーの Xcode 16.x で検証しています)。
git clone https://github.com/tsuvic/agentbar
cd agentbar
swift build
# 実行。ウィンドウは開きません。
# メニューバー(時計の左)にゲージアイコンが現れます。
swift run AgentBar
# テスト。プロセス非起動の回帰テストを含みます(172 テスト)。
swift testHomebrew Cask
予定Cask の定義はリポジトリの distribution/agentbar.rb にありますが、公開タップはまだ作成していません。それまでは DMG を利用してください。
# 公開準備ができ次第アナウンスします。
brew install --cask agentbarMenuBarExtra の popover、Dock アイコンをクリックすると Graph ウィンドウが開きます。アンインストールは AgentBar.app をゴミ箱へ移動するだけです。残すのは ~/Library/Preferences/com.tsuvic.agentbar.plist の更新間隔の設定だけで、必要なら削除してください。起動後の操作は 使い方 で説明しています。
02 · 使い方
使い方
メニューバーのゲージアイコンをクリックすると、幅 320pt の popover が開きます。タブは Active / Usage / History / Update / Diag の 5 つで、開いたときは Active が表示されます。アイコンの横のラベルには Claude の週間クォータ(ある場合)、なければ本日の合計トークン数が出ます。
ライブ活動モニター
セッションディレクトリをファイルポーリングで監視し、変更があるとトレースを再読込(10 秒スロットル)。各エージェントの「今」を実行中 / 承認待ち / 入力待ち / 完了 / 失敗 で表示します。
承認待ち・入力待ちの Run は Needs attention として最上位に表示されます。Claude の承認待ちは生 JSONL 末尾の未完了 tool_use と result レコードからの検出です。Codex / Qwen / Cursor は会話ターン由来の最善推定です。
ヘッダから Graph ウィンドウを開くと、エージェント間の呼び出し関係がインデントツリーで表示されます。仕組みはアーキテクチャの項で説明しています。
使用量モニター
Claude / Codex / Qwen / Gemini / Cursor / Command Code / OpenCode / Hermes の 8 プロバイダを行で表示。各行に本日トークン・7 日間合計・取得からの経過時間。
トークンは input / output / cache read / cache creation / reasoning に内訳保持。モデル別の集計も表示します。
クォータバーは 80% 未満がアクセント色、80% 以上で warning、100% で danger。Claude は ~/.claude/usage-watch/rate-limits.json から 5 時間 / 週間の制限を読み取ります。
更新間隔はフッターのメニューから選択(Manual / 5 / 15 / 30 / 60 分)。最短は意図的に 5 分です。1 分更新は CodexBar で問題を起こした設定の一つでした。
取得に失敗しても最後の正常データを保持し、取得時刻を併記します(stale-while-revalidate)。
履歴と会話の詳細
直近 60 日・各プロバイダ最大 500 件のセッション一覧。プロジェクト・モデル・トークン・メッセージ数・時刻・コスト推定を 1 行にまとめ、プロバイダで絞り込めます。
セッションを選ぶと会話ターン(user / assistant / tool)を直接閲覧できます。モデルとトークン付きです。
ツールアップデーター
インストール方法を問わず AI ツールを検出します。
| 方式 | 検出 | 更新 |
|---|---|---|
| npm global | 「npm root -g」以下の package.json | npm install -g <pkg>@latest |
| Homebrew formula | brew list --versions | brew upgrade <formula> |
| Homebrew cask | brew list --cask | brew upgrade --cask <cask> |
| App bundle | /Applications/*.app の Info.plist | パッケージマネージャ経由のみ |
| バイナリ | ~/.local/bin 等を --version で確認 | パッケージマネージャ経由のみ |
チェックも更新もユーザーが操作したときだけ実行。定期ポーリングはしません。すべてのコマンドにハードタイムアウト付き(SIGTERM → 猶予 → SIGKILL)。
自己診断
直近の使用量取得について、AgentBar 自身のふるまいを報告します。
- 所要時間と CPU 時間
- メモリ(RSS)
- 読み取ったファイル数 / パースしたレコード数
- 起動した禁止プロセス数(常に 0 であるべき)
- 終了理由(success / timedOut / circuitOpen / forbiddenProcess)
「自分が置き換えようとしているもの」にならないための監視です。しきい値を超えたプロバイダは自動で停止します。
セッション一覧から会話ターンへ
History タブは、日次の使用量と同じローカルファイルをセッション単位で読み解きます。プロバイダ横断の一覧(プロジェクト・git ブランチ・メッセージ数・トークン数・主モデル・最終活動)から、個々の会話ターン(user / assistant / tool、タイムスタンプ、モデル、ターンごとのトークン)へドリルダウンできます。
- agentbarmain1.24Mtokensclaude128 msgsclaude-sonnet2時間前
- sitefeat/docs310.4ktokenscodex42 msgsgpt-5-codex5時間前
- pixeldexdevelop890.2ktokensqwen67 msgsqwen-max昨日
- resume—cursor23 msgscomposer3日前
CodexBar の issues 200 件を分類して、設計上の原因をまとめて。
確認しました。根本原因は「使用量を読むためだけにフルスタックの CLI を起動する」設計で、#2052 の自動更新トラフィックや #1844 のブラウザ起動はすべてそこから派生しています…
モデル別のトークン内訳からはコスト推定(USD)も計算します。これはつねに推定値です。サブスクリプションプランでカバー済みの用量は課金対象外の場合があり、内訳が分からないソースでは最も高い output レートで全量を見積もるため、実際より高く出ます。請求の根拠には使えません。
03 · アーキテクチャ
なぜ軽くいられるのか
既定の使用量データは、エージェントがすでにディスクへ書き込んでいるファイルから読めます。通常取得は「タイマー → ファイルを開く → パース → 表示」の4段階で、サブプロセスもネットワークも挟みません。
ディスク
エージェントが自分で書くファイル
Claude
~/.claude/projects/**/*.jsonl
Codex
~/.codex/sessions/YYYY/MM/DD/*.jsonl
Qwen
~/.qwen/projects/<project>/chats/*.jsonl
Cursor
…/Cursor/User/globalStorage/state.vscdb
ProviderCoordinator
actor。取得はすべてここを通る
単一飛行 / 同一プロバイダの取得中は新たな取得を起動せず、実行中の結果を共有します。
ハードタイムアウト / 遅い取得は強制打ち切り。既定 10 秒。
サーキットブレーカー / 3 回連続失敗でそのプロバイダを 15 分停止。
CPU バジェット / 1 回の取得 CPU が 1.5 秒を超えたら、そのプロバイダを停止。
ProcessGuard / 取得前後でプロセステーブルを差分し、禁止プロセスの出現を取得失敗として扱う。
Stale-while-revalidate / 失敗しても最後の正常データを保持し、取得時刻を明示。
UsageSnapshot
UI が描画する唯一のもの
日次のトークン集計・クォータ・セッション一覧・自己診断をまとめた不変スナップショット。popover はこれを表示するだけで、取得を直接トリガーしません。
取得を守る 6 つの機構
- 単一飛行
- 同一プロバイダの取得中は新たな取得を起動せず、実行中の結果を共有します。
- ハードタイムアウト
- 遅い取得は強制打ち切り。既定 10 秒。
- サーキットブレーカー
- 3 回連続失敗でそのプロバイダを 15 分停止。
- CPU バジェット
- 1 回の取得 CPU が 1.5 秒を超えたら、そのプロバイダを停止。
- ProcessGuard
- 取得前後でプロセステーブルを差分し、禁止プロセスの出現を取得失敗として扱う。
- Stale-while-revalidate
- 失敗しても最後の正常データを保持し、取得時刻を明示。
ProcessGuard。「起動しない」を実行時に証明する
ProcessGuard は取得の前後でプロセステーブル(sysctl(KERN_PROC_ALL)、それ自体も in-process syscall)のスナップショットを撮り、差分に禁止プロセスが現れていたら forbiddenProcess としてその取得を失敗扱いにします。設計上の約束が、実行時の自己防衛になっています。禁止リスト:
nodepythonnpmnpxuvchromeclaudecodexqwenbashshzsh…NoProcessSpawnTests)でも強制されています。使用量取得のコードパスがサブプロセスを起動しようとすると、テストが失敗します。Graph ウィンドウの 3 ペイン
Active タブから開く別ウィンドウ(GraphWindowView)は、トレースグラフを 3 つの視点から表示します。
- Graph
- エージェント間の呼び出し関係のインデントツリー。Claude が codex exec を呼び、その Codex が claude -p を呼ぶ、といった連鎖をログから再構成します。ノードは Run(実行単位)なので、--resume や再実行でも親子関係が壊れません。
- Analysis
- プロバイダ別のトークン・推定コスト・キャッシュヒット率・Run 数に加え、グラフ健全性(最大深度による連鎖の深さ警告・孤児 Run)とボトルネック(最長 Run)を算出します。
- Rules
- ユーザー自身のエージェント設定ファイルを管理します。グローバルの標準ロケーション(~/.codex/AGENTS.md、~/.claude/CLAUDE.md 等)を設定の有無に関わらず一覧し、存在は緑・未設定は灰で表示、選択すると編集できます。プロジェクトも同じ論理で一覧し、Compare トグルでグローバルとプロジェクトを並べて重複行を確認できます。「どのツールがどれを読むか」の対応表(RulesCatalog、2026 年版)は ? リファレンスに格納。@AGENTS.md 未 import などの不整合も指摘します。
呼び出し辺は推定です。EdgeDetector がツール呼び出しのコマンド(codex exec / claude -p / qwen / gemini)を検出し、時刻と作業ディレクトリで新規セッションを相関させて生成します。
モジュール構成
AgentBarCore (ライブラリ)
├── Models / Support 型、UsageProvider プロトコル(fetch/sessions/conversation/runSignal)
├── Providers/
│ ├── ClaudeProvider JSONL + rate-limits.json(usage/sessions/conversation/正確な runSignal)
│ ├── CodexProvider 日付ディレクトリ JSONL(session_meta/event_msg/response_item)
│ ├── QwenProvider chats JSONL(usageMetadata)+ usage_record.jsonl
│ └── CursorProvider SQLite(state.vscdb)を sqlite3 C API で直接読取
├── Trace/
│ ├── TraceModels AgentRun / TraceEvent / TraceEdge / AgentTrace / TraceGraph + RunState
│ ├── RunStateClassifier RunSignal → 状態分類(純粋)
│ ├── RunSignalDerivation 会話ターンからの最善推定 RunSignal(既定経路)
│ ├── ActivityWatcher ファイルポーリング監視、変更を AsyncStream で配信(actor)
│ ├── EdgeDetector 他エージェント起動コマンド検出 + 時刻/cwd 相関 → 推定辺
│ ├── TraceBuilder sessions + signals + edges を TraceGraph へ(actor + 純粋 TraceAssembler)
│ └── TraceAnalysis プロバイダ集計・キャッシュヒット率・グラフ健全性(純粋)
├── Rules/
│ ├── RulesCatalog ファイル→対応ツールの単一テーブル(2026 年版)
│ ├── RulesScanner プロジェクト走査・glob マッチ・不整合指摘
│ ├── GlobalRulesCatalog ホーム直下の標準ロケーション+走査
│ └── RulesCompare グローバル/プロジェクトの対照・共有行(純粋関数)
├── ProviderCoordinator actor。単一飛行・サーキットブレーカー・ハードタイムアウト・
│ スタッガースケジュール・自己監視・ProcessGuard・履歴集約
├── ProcessGuard sysctl でプロセステーブルを差分監視(spawn 検出)
├── SelfMonitor getrusage / task_info による自己 CPU・RSS 計測
├── Cost CostCalculator(モデル単価テーブル、純粋関数)
├── Redaction 診断/ログ用のパス・秘密情報マスク
└── Updater/ ToolUpdateService(actor)+ ToolCatalog + SystemCommandRunner
AgentBar (実行ファイル)
└── SwiftUI MenuBarExtra + Window
├── メニューバー Active / Usage / History / Update / Diag の5タブ(幅320pt固定)
└── Graph ウィンドウ Graph / Analysis / Rules の3ペイン(トレースツリー+詳細)CodexBar の公開 Issues 報告から設計上の問題点を整理したセクションと、エージェント起動方式との比較表(公開 Issues 報告に基づく)は、プロダクトページのにまとめています。
04 · プライバシー
プライバシー
AgentBar はローカル動作が既定です。会話本文は送信せず、明示設定したリモート usage だけが指定 endpoint と通信します。
しないこと
- テレメトリ・アナリティクス・クラッシュレポートを送信しません。
- ネットワークは既定ゼロ。明示設定したリモート usage だけが例外です。
- Keychain へのアクセスや、認証情報・API キー・トークンの読み取りは行いません。
- ブラウザや認証ダイアログをバックグラウンドで開きません。
読み取ること
エージェントが自分でディスクに書いたファイルだけを読みます。
~/.claude/projects/**/*.jsonl と ~/.claude/usage-watch/rate-limits.json~/.codex/sessions/YYYY/MM/DD/*.jsonl~/.qwen/projects/<project>/chats/*.jsonl と ~/.qwen/usage_record.jsonl~/Library/Application Support/Cursor/User/globalStorage/state.vscdb(読み取り専用)
SQLITE_OPEN_READONLY で開きます。書き込みは発生しません。会話のテキストは表示のためにローカルで読むだけで、保存も送信もしません。brew / npm 等をサブプロセスとして実行します。すべてハードタイムアウト付き(SIGTERM → 猶予 → SIGKILL)で、定期実行はしません。使用量の定期取得がサブプロセスを生むことはありません。~/Library/Preferences/com.tsuvic.agentbar.plist)。ログや会話の写しは保存しません。データフローと保持の詳細は、リポジトリの docs/PRIVACY.md にまとめています。プライバシー上の懸念は GitHub Issues で報告してください。
05 · FAQ
FAQ
よくある質問。設計の比較はプロダクトページにもまとめています。
エージェントが自分でディスクに書いたファイルだけです。Claude は ~/.claude/projects/**/*.jsonl と ~/.claude/usage-watch/rate-limits.json、Codex は ~/.codex/sessions/YYYY/MM/DD/*.jsonl、Qwen は ~/.qwen/projects/<project>/chats/*.jsonl、Cursor はローカルの state.vscdb(SQLite、読み取り専用)を読みます。
認証情報・API キー・Keychain には触れません。詳細はアーキテクチャのデータソース表とプライバシーの項を参照してください。
いいえ、推定値です。モデルファミリーごとの公開リスト価格(USD/1M トークン)から計算します。サブスクリプションプランの用量は課金対象外の場合があり、その場合は実際より高く出ます。
また、トークン総量しか分からないソースでは最も高い output レートで全量を見積もるため、やはり高めになります。請求の根拠には使わず、傾向を掴む用途に使ってください。
Cursor がローカルに持つ SQLite データベース(state.vscdb)を読み取り専用で開き、composer のセッションとメッセージを表示します。Cursor はメッセージごとのトークンを確実に記録していないため、トークン数は「—」表示です。
Cursor はバージョンごとにスキーマを変えるため、すべての読み取りは防御的に行います。壊れたスキーマでもアプリは落ちず、そのセッションはスキップします。
使用量取得はファイル読み取りのみです。加えて ProcessGuard が取得前後でプロセステーブルを差分し、node / npm / chrome 等の出現を検出したら取得を失敗扱いにします。この保証は回帰テストでも強制されています。
サブプロセスが動くのは、あなたがアップデーターの「更新」を押したときだけです。
チェックも更新もユーザー操作のときだけ実行され、定期ポーリングはしません。すべてのコマンドにハードタイムアウト(SIGTERM → 猶予 → SIGKILL)がかかります。
実際の更新処理は brew / npm といった正規のパッケージマネージャが行います。AgentBar はそれらを呼び出すだけです。
最後の正常データを保持したまま、取得時刻を併記して表示します(stale-while-revalidate)。CodexBar のようにキャッシュを破棄してデータ欠落を起こすことはありません(公開 Issue #2241 で報告された挙動です)。
3 回連続で失敗したプロバイダはサーキットブレーカーで 15 分停止し、リトライの嵐を起こしません。
CodexBar の問題は「使用量を読むためにフルスタックの CLI を起動する」という設計そのものから派生しています。この整理は公開 Issues 報告(#1844 / #2052 / #2251 / #2241 / #1999 / #1998 等)に基づきます。抜粋はプロダクトページのにまとめています。
AgentBar は「そもそも起動しない」設計で作り直したものです。同じデータを、ファイル読み取りだけで得ます。
動きます。配布物は Apple Silicon / Intel 両対応の universal binary です。要件は macOS 14(Sonoma)以降だけです。
Active タブから開く別ウィンドウで、エージェント間の呼び出し関係(Claude が codex exec を呼び、その Codex が claude -p を呼ぶ、等)をインデントツリー表示します。Graph / Analysis / Rules の 3 ペイン構成で、Analysis はキャッシュヒット率とボトルネック、Rules はグローバルとプロジェクトのエージェント設定ファイルを存在別(緑/灰)に一覧し、編集と並べて比較ができます。詳細はアーキテクチャの項を参照してください。