feat: add provider usage tracking

docs/cli/index.md

@@ -305,9 +305,24 @@ Show linked session health and recent recipients.
 Options:
 - `--json`
 - `--deep` (probe providers)
+- `--usage` (show provider usage/quota)
 - `--timeout <ms>`
 - `--verbose`
 
+### Usage tracking
+Clawdbot can surface provider usage/quota when OAuth/API creds are available.
+
+Surfaces:
+- `/status` (adds a short usage line when available)
+- `clawdbot status --usage` (prints full provider breakdown)
+- macOS menu bar (Usage section under Context)
+
+Notes:
+- Data comes directly from provider usage endpoints (no estimates).
+- Providers: Anthropic, GitHub Copilot, Gemini CLI, Antigravity, OpenAI Codex OAuth, plus z.ai when an API key is configured.
+- If no matching credentials exist, usage is hidden.
+- Details: see [Usage tracking](/concepts/usage-tracking).
+
 ### `health`
 Fetch health from the running Gateway.
 

docs/concepts/usage-tracking.md

@@ -0,0 +1,27 @@
+---
+summary: "Usage tracking surfaces and credential requirements"
+read_when:
+  - You are wiring provider usage/quota surfaces
+  - You need to explain usage tracking behavior or auth requirements
+---
+# Usage tracking
+
+## What it is
+- Pulls provider usage/quota directly from their usage endpoints.
+- No estimated costs; only the provider-reported windows.
+
+## Where it shows up
+- `/status` in chats: adds a short “Usage” line (only if available).
+- CLI: `clawdbot status --usage` prints a full per-provider breakdown.
+- macOS menu bar: “Usage” section under Context (only if available).
+
+## Providers + credentials
+- **Anthropic (Claude)**: OAuth tokens in auth profiles.
+- **GitHub Copilot**: OAuth tokens in auth profiles.
+- **Gemini CLI**: OAuth tokens in auth profiles.
+- **Antigravity**: OAuth tokens in auth profiles.
+- **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
+- **z.ai**: API key via env/config/auth store.
+
+Usage is hidden if no matching OAuth/API credentials exist.
+

docs/platforms/mac/menu-bar.md

@@ -9,6 +9,7 @@ read_when:
 - We surface the current agent work state in the menu bar icon and in the first status row of the menu.
 - Health status is hidden while work is active; it returns when all sessions are idle.
 - The “Nodes” block in the menu lists **devices** only (gateway bridge nodes via `node.list`), not client/presence entries.
+- A “Usage” section appears under Context when provider usage snapshots are available.
 
 ## State model
 - Sessions: events arrive with `runId` (per-run) plus `sessionKey` in the payload. The “main” session is the key `main`; if absent, we fall back to the most recently updated session.