ドキュメント

インストールから内部設計まで、
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 の両方に常駐します。

初回起動を Gatekeeper にブロックされる場合は、DMG が壊れているか改変されている可能性があります。正規の配布物は署名・ノータリゼーション済みで、通常は確認なしに開けます。ブロックされたら再ダウンロードしてください。

ソースからビルド

利用可能

リポジトリをクローンして swift run。ビルドには Xcode 16 以降の Swift 6 ツールチェーンが必要です(CI は macOS 15 ランナーの Xcode 16.x で検証しています)。

terminal
git clone https://github.com/tsuvic/agentbar
cd agentbar

swift build

# 実行。ウィンドウは開きません。
# メニューバー(時計の左)にゲージアイコンが現れます。
swift run AgentBar

# テスト。プロセス非起動の回帰テストを含みます(172 テスト)。
swift test

Homebrew Cask

予定

Cask の定義はリポジトリの distribution/agentbar.rb にありますが、公開タップはまだ作成していません。それまでは DMG を利用してください。

terminal
# 公開準備ができ次第アナウンスします。
brew install --cask agentbar
起動するとメニューバーと Dock の両方にアイコンが現れ、起動時にウィンドウは開きません。メニューバーアイコンは使用量や承認待ちをちら見する MenuBarExtra の popover、Dock アイコンをクリックすると Graph ウィンドウが開きます。

アンインストールは AgentBar.app をゴミ箱へ移動するだけです。残すのは ~/Library/Preferences/com.tsuvic.agentbar.plist の更新間隔の設定だけで、必要なら削除してください。起動後の操作は 使い方 で説明しています。

02 · 使い方

使い方

メニューバーのゲージアイコンをクリックすると、幅 320pt の popover が開きます。タブは Active / Usage / History / Update / Diag の 5 つで、開いたときは Active が表示されます。アイコンの横のラベルには Claude の週間クォータ(ある場合)、なければ本日の合計トークン数が出ます。

Active

ライブ活動モニター

セッションディレクトリをファイルポーリングで監視し、変更があるとトレースを再読込(10 秒スロットル)。各エージェントの「今」を実行中 / 承認待ち / 入力待ち / 完了 / 失敗 で表示します。

承認待ち・入力待ちの Run は Needs attention として最上位に表示されます。Claude の承認待ちは生 JSONL 末尾の未完了 tool_useresult レコードからの検出です。Codex / Qwen / Cursor は会話ターン由来の最善推定です。

ヘッダから Graph ウィンドウを開くと、エージェント間の呼び出し関係がインデントツリーで表示されます。仕組みはアーキテクチャの項で説明しています。

Usage

使用量モニター

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)。

History

履歴と会話の詳細

直近 60 日・各プロバイダ最大 500 件のセッション一覧。プロジェクト・モデル・トークン・メッセージ数・時刻・コスト推定を 1 行にまとめ、プロバイダで絞り込めます。

セッションを選ぶと会話ターン(user / assistant / tool)を直接閲覧できます。モデルとトークン付きです。

Update

ツールアップデーター

インストール方法を問わず AI ツールを検出します。

方式検出更新
npm global「npm root -g」以下の package.jsonnpm install -g <pkg>@latest
Homebrew formulabrew list --versionsbrew upgrade <formula>
Homebrew caskbrew list --caskbrew upgrade --cask <cask>
App bundle/Applications/*.app の Info.plistパッケージマネージャ経由のみ
バイナリ~/.local/bin 等を --version で確認パッケージマネージャ経由のみ

チェックも更新もユーザーが操作したときだけ実行。定期ポーリングはしません。すべてのコマンドにハードタイムアウト付き(SIGTERM → 猶予 → SIGKILL)。

Diag

自己診断

直近の使用量取得について、AgentBar 自身のふるまいを報告します。

  • 所要時間と CPU 時間
  • メモリ(RSS)
  • 読み取ったファイル数 / パースしたレコード数
  • 起動した禁止プロセス数(常に 0 であるべき)
  • 終了理由(success / timedOut / circuitOpen / forbiddenProcess)

「自分が置き換えようとしているもの」にならないための監視です。しきい値を超えたプロバイダは自動で停止します。

セッション一覧から会話ターンへ

History タブは、日次の使用量と同じローカルファイルをセッション単位で読み解きます。プロバイダ横断の一覧(プロジェクト・git ブランチ・メッセージ数・トークン数・主モデル・最終活動)から、個々の会話ターン(user / assistant / tool、タイムスタンプ、モデル、ターンごとのトークン)へドリルダウンできます。

sessions最終活動順
  • agentbarmain1.24Mtokens
    claude128 msgsclaude-sonnet2時間前
  • sitefeat/docs310.4ktokens
    codex42 msgsgpt-5-codex5時間前
  • pixeldexdevelop890.2ktokens
    qwen67 msgsqwen-max昨日
  • resume
    cursor23 msgscomposer3日前
conversationagentbar @ main
user14:12

CodexBar の issues 200 件を分類して、設計上の原因をまとめて。

assistant14:12claude-sonnet4,218 tokens

確認しました。根本原因は「使用量を読むためだけにフルスタックの CLI を起動する」設計で、#2052 の自動更新トラフィックや #1844 のブラウザ起動はすべてそこから派生しています…

このセッションのコスト推定$1.87input $0.21 / output $1.42 / cache $0.24推定値

モデル別のトークン内訳からはコスト推定(USD)も計算します。これはつねに推定値です。サブスクリプションプランでカバー済みの用量は課金対象外の場合があり、内訳が分からないソースでは最も高い output レートで全量を見積もるため、実際より高く出ます。請求の根拠には使えません。

Active も History も追加のプロセスを起動しません。Claude / Codex / Qwen は JSONL を再パースし、Cursor はローカルの SQLite データベースを読み取り専用で開くだけです。

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。取得はすべてここを通る

単一飛行

ハードタイムアウト

サーキットブレーカー

CPU バジェット

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)を検出し、時刻と作業ディレクトリで新規セッションを相関させて生成します。

モジュール構成

Sources/
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(読み取り専用)
Cursor のデータベースは SQLITE_OPEN_READONLY で開きます。書き込みは発生しません。会話のテキストは表示のためにローカルで読むだけで、保存も送信もしません。
サブプロセス起動の例外はアップデーターです。あなたが「更新」を押したときだけ brew / npm 等をサブプロセスとして実行します。すべてハードタイムアウト付き(SIGTERM → 猶予 → SIGKILL)で、定期実行はしません。使用量の定期取得がサブプロセスを生むことはありません。
アプリが永続化するのは更新間隔の設定 3 つだけです(~/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 はグローバルとプロジェクトのエージェント設定ファイルを存在別(緑/灰)に一覧し、編集と並べて比較ができます。詳細はアーキテクチャの項を参照してください。

AgentBar を入手

軽いかどうかは、自分の Mac で確かめてください。

AgentBar は、エージェントがすでに書き出しているローカルファイルを読むだけで成り立っています。使用量や履歴を得るために CLI・MCP・ブラウザ・エージェントを起動しません。Diag タブは AgentBar 自身の CPU・メモリ・起動したプロセス数(常に 0)を報告します。macOS 14+ · Swift 6 / SwiftUI · ソースは GitHub で公開しています。

git clone https://github.com/tsuvic/agentbar