UsageMax public observability

UsageMax は、コンピューター上にすでにある AI の利用履歴を集約し、トークン数、モデル構成、追跡したコスト、セッション、アクティビティをわかりやすく表示します。オープンソースの CLI は、範囲を限定してローカルスキャンを実行し、集計済みスナップショットをバージョン管理された UsageMax API にアップロードします。

要約： 1 回限りのコレクターで、デフォルトでは非公開。公開するかどうかは選択できます。プロンプトと生成内容がコンピューターの外に送られることはありません。

利用できる機能

領域	目的
プライベートワークスペース	テナント単位の 1 つのビューで、コンピューター、プロバイダー、モデル、プロジェクト、コストセンターを比較できます。
公開プロフィール	オプトイン方式のプロフィール、ランキング、アクティビティ、モデル構成、推定コスト、連続利用状況を表示します。
コレクター API	インストールに紐付けられた、書き込み専用のスナップショットと、コンテンツを含まないテレメトリーを扱います。
usagemax CLI	アーカイブからの復旧、安全な診断、任意の OS スケジュール設定に対応した、bunx で利用しやすいスキャナーです。
エージェントインターフェイス	範囲を限定した OpenAPI、MCP、Markdown、WebMCP、A2A、およびインストール可能なスキルを提供します。

物理的な HUD／画面プロジェクトは、意図的にこのリポジトリとは分離されています。 UsageMax のテレメトリーを利用できますが、プラットフォームの利用に必須ではありません。

コンピューターを接続する

1. リンクコードを作成する

usagemax.com/account にサインインし、 コンピューターをリンクを選択して名前を付け、1 回限りのコマンドをコピーします。コードの有効期間は 10 分で、1 回だけ使用できます。

2. リンクして同期する

履歴を保持しているコンピューターまたは WSL ディストリビューションで、コマンドを実行します。

bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX

# Optional explicit name; the account keeps this name for the installation.
bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX --name "Work laptop"

初回のリンクでは、1 回限りの完全な同期が実行されます。各インストールには安定したランダム ID が割り当てられるため、再リンクや名前の変更時にはキーがローテーションされますが、デバイスが重複して作成されることはありません。

3. 任意のタイミングで集計する

bunx usagemax sync --dry-run --explain  # inspect the bounded plan
bunx usagemax sync                      # upload changed usage
bunx usagemax sync --full               # reconcile all retained history
bunx usagemax status --remote            # check the saved credential safely

CLI の更新と進捗

CLI は npm の latest dist-tag を 1 日に最大 2 回確認します。usagemax update を実行すると、Bun または npm を通じてグローバルインストールを更新できます。読み取り専用で確認するには --check を使用します。usagemax update sync を実行すると、@latest を入力せずにコマンドを現在のリリースに引き継げます。または、USAGEMAX_AUTO_UPDATE=1 を設定すると、明示的な自動引き継ぎが有効になります。オフライン環境では --no-update-check を使用するか、USAGEMAX_DISABLE_UPDATE_CHECK=1 を設定してください。対話型ターミナルでは stderr に小さな進捗行が表示されます。JSON、quiet、CI、およびスケジュール実行では、機械可読性が保たれ、出力は抑制されます。

対応範囲と正確性

UsageMax は ccusage v20.0.24 を固定し、16 のアダプターを使用します。対象は Amp、Claude Code、Codebuff、Codex、GitHub Copilot CLI、Factory Droid、Gemini CLI、Goose、Grok Build、Hermes、Kilo Code、Kimi CLI、OpenClaw、OpenCode、Pi、Qwen Code です。名前付きの Pi 形式のストアも検出されます。

収集機能は、サポート対象のプロバイダー上書き設定、範囲を限定したホームディレクトリ、Claude Desktop のセッション、.cc-mirror、名前が変更された Claude／Codex のバックアップフォルダー、WSL からのサポート対象 Windows ホームを認識します。通常の同期では、既知の場所とホームディレクトリ直下の項目を調べます。ディスク全体を走査することはありません。

bunx usagemax doctor                 # metadata-only coverage check
bunx usagemax doctor --deep --json   # retained-history audit
bunx usagemax sync --archives        # one-time compressed-history recovery
bunx usagemax report                 # local ccusage report
bunx usagemax status --json          # version, coverage, checkpoints, and link state
bunx usagemax update --json          # machine-readable npm release check

フルスキャンでは、2024 年以降に保持された履歴をカタログ化できます。読み取り可能なファイルの一覧があっても、集計パーサーがすべてのファイルと日付を処理した証明にはなりません。UsageMax はこの 2 つの状態を個別に報告します。カウンターの減少や行の欠落は、パーサーが対象範囲を明示的に保証しない限り、保護されます。不明なモデルは unattributed のままとなり、不明な料金は不明のままです。

Cursor、Windsurf、Aider、Continue、Cline、Roo Code、ホスト型エージェント、プロバイダー API への直接トラフィック、およびエンタープライズの課金システムは、すべてが安定したローカル台帳を公開しているわけではありません。これらのデータはネイティブまたは OTLP/HTTP JSON の契約を通じて取り込むか、ローカルの証跡が利用できない場合はプロバイダーの課金エクスポートを使用してください。

プライバシーとリソース使用量

コンピューター上に保持	アップロードされる可能性がある情報
プロンプトと補完	集計されたトークンカウンター
ソースコードとファイルの内容	プロバイダー、モデル、ソースの名前
プロジェクトのパスとツールのペイロード	日付、コスト、対象範囲の状態
プロバイダーの認証情報とシークレット	不透明な SHA-256 セッション ID

CLI の実行時間は短くなっています。変更のないインベントリはスキップし、必要な日付範囲のみを解析します。重複実行を防ぐためにローカルロックを使用し、実行ごとにパッケージをダウンロードすることはありません。オプションのスケジュール実行は同じ単発プロセスを呼び出し、失敗後は実行間隔を延ばします。

bun install -g usagemax
usagemax service install          # approximately every 15 minutes
usagemax service install --every 30
usagemax service status
usagemax service uninstall

スケジュール実行は任意です。macOS ではユーザー LaunchAgent、Linux／WSL ではユーザー systemd タイマー、Windows ではタスク スケジューラを使用します。スリープ中またはバッテリー駆動中のコンピューターを不必要に起動することはありません。

認証情報と安全な診断

UsageMax では、ウェブサイトへのサインイン、1 回限りのリンク、コレクターへの書き込みに、それぞれ異なる認証情報を使用します。コレクターキーは、umx_ の後に小文字の 16 進数 64 文字が続く形式です。サーバー側で生成され、一度だけ表示され、ローカルではユーザーのみがアクセスできる権限で保存されます。UsageMax では SHA-256 ハッシュのみを保存します。

Advanced · custom telemetry collector キーを使用する場合は、標準入力経由でシークレットを渡してください。コマンドライン引数、URL、リクエスト本文、リポジトリ、ログには決して含めないでください。

set +x
set -o pipefail
printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
  | bunx usagemax token status \
      --json \
  | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'

token status と telemetry test は CLI 0.3.11 に含まれています。新しい環境でも古い npm タグが残っている場合は、usagemax update token status を実行するか、新しいパッケージが公開されるまで、このリポジトリから node packages/cli/src/cli.js token status を使用してください。

認証済みの書き込み経路を検証するには、トークンとコストの値をすべて 0 に設定した、コンテンツを含まない agent_state イベントを 1 つ送信します。

set +x
set -o pipefail
printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
  | bunx usagemax telemetry test \
      --token-stdin \
      --json

これは可観測性イベントを 1 つ書き込みますが、トークンや支出の合計は変更しません。未バインドの Advanced キーは、最初に書き込みが受理されたとき、この CLI インストールにバインドされます。認証情報で取り込みができない場合、または API がイベントを拒否した場合、CLI は 0 以外の終了コードを返します。

数値による判定は、意図的に簡潔にしています。

結果	意味
200 1	認識され、有効で、取り込みが許可されています。
200 0	認識されていますが、ブロックされています。秘匿化された JSON ステータスを確認してください。
409 0	インストール UUID がキーのバインド先と一致しません。
401 0	形式またはキーが受理されませんでした。サーバーは理由を明らかにしません。

読み取り専用の診断では、認証情報の種類、スコープ、有効化状態、プロフィール／名前、バインド状態、最後に受理または拒否された書き込みが報告されます。トークン、そのハッシュ、認可された UUID は返されません。Advanced キーは直ちに有効になり、最初の有効な書き込み時にバインドされます。リンク済みの CLI キーは、リンク交換時にバインドされます。

エージェントと開発者向けのインターフェース

インターフェース	URL
OpenAPI	openapi.json
エージェント機能ビュー	/?mode=agent
パブリック MCP	server-card.json
ドキュメント MCP	/docs-mcp
A2A カード	agent-card.json
スキルインデックス	agent-skills/index.json
MCP Registry メタデータ	server.json
スキルのソースとインストール方法	skills/ · skills.sh
認証ガイド	/auth.md

パブリックな読み取りは範囲が制限されており、認証は不要です。パブリック MCP サーバーはステートレスかつ読み取り専用で、非公開のワークスペースデータやコレクターの認証情報は公開しません。コレクターへの取り込みは、別の認証済み API 境界で行われます。

リポジトリの構成

src/             Next.js web app, public routes, docs, and UI
convex/          Convex schema, authorization, ingestion, and projections
packages/cli/    Distributable `usagemax` package
docs/            Architecture, contracts, coverage, operations, and releases
skills/          Direct-installable agent skills and source notes
server.json      MCP Registry submission metadata for the public remote server

ドキュメントの構成を確認するには、docs/README.md から始めてください。公開向けの製品・インテグレーションガイドと、コントリビューター、運用担当者、リリース、過去の記録に関するドキュメントが分けられています。

MCP Registry と skills.sh のステータス

公開 MCP サーバーは、公式 Registry に io.github.SYMBaiEX/[email protected] として公開されています。server.json ファイルは、このリスティングのバージョン管理されたソースメタデータです。パッケージや認証情報に関する主張は含まれていません。3 つの skills/ カードには、有効な name と description のフロントマターがあり、 skills.sh にインデックスされています。

npx skills add SYMBaiEX/usagemax --skill usage-observability
npx skills add SYMBaiEX/usagemax --skill enterprise-reporting
npx skills add SYMBaiEX/usagemax --skill collector-diagnostics

ダイジェストで固定された Agent Skills インデックス はデプロイ済みの一覧であり、GitHub の生ファイルはインストール元です。このディレクトリの自動セキュリティ監査の状態は、このリポジトリの外部にあり、これらのファイルとは独立して変わる場合があります。

開発

必要要件：Bun 1.4.2 と Node.js 20 以降です。Web アプリには、設定済みの Convex 開発デプロイメントも必要です。

bun install
bun run check       # lint, typecheck, tests, and production build
bun run cli:pack    # verify the publishable CLI archive

ローカルで Web 開発を行うには、無視対象の .env.local を設定してから、bunx convex dev と bun run dev を実行します。コントリビューションの範囲については CONTRIBUTING.md を、リリースゲートについては docs/RELEASE.md をご覧ください。

オープンソース

UsageMax は MIT License のもとでリリースされています。サードパーティ依存関係に関する通知は NOTICE.md にあります。脆弱性の疑いがある場合は、公開 issue ではなく、SECURITY.md を通じて非公開で報告してください。