@slkiser/opencode-quota 3.8.8 → 3.10.0

package/README.md

@@ -35,7 +35,7 @@ The installer adds missing plugin/config entries and keeps your unrelated settin
 | Question | Pick this when you want... |
 | --- | --- |
 | Install scope | This repo/worktree only, or your global OpenCode config. |
-| Quota UI | Sidebar panel, toasts, compact status line, terminal/slash-command only, or a mix. |
+| Quota UI | Sidebar panel, toasts, compact status line, terminal command only, or a mix. Sidebar or Compact status installs the TUI plugin for slash-command dialogs. |
 | Provider mode | Auto-detect providers, or choose a provider list yourself. |
 | Quota reset periods | Show one reset period per provider, or all known reset periods. |
 | Quota percentage meaning | Show quota remaining, or quota already used. |
@@ -45,9 +45,9 @@ The installer adds missing plugin/config entries and keeps your unrelated settin
 ### After install
 
 1. Restart OpenCode.
-2. Run `/quota`.
-3. If something looks wrong, run `/quota_status`.
-4. If you kept maintainer announcements enabled and installed the TUI plugin, the home screen can show `Notice: Maintainer announcement available. Run /quota_announcements.` or the plural count form. Without the TUI plugin, the same count-only notice can appear once after the first visible quota toast. Run `/quota_announcements` to read active notices.
+2. If you selected Sidebar or Compact status, run `/quota`. If you selected Toast-only or Terminal command only, use `opencode-quota show` or add the TUI plugin manually for slash commands.
+3. If something looks wrong and the TUI plugin is installed, run `/quota_status`; otherwise run `opencode-quota show` from your terminal.
+4. If you kept maintainer announcements enabled and installed the TUI plugin, the home screen can show `Notice: Maintainer announcement available. Run /quota_announcements.` or the plural count form. Without the TUI plugin, the same count-only notice can appear once after the first visible quota toast. Run `/quota_announcements` to read active notices when the TUI plugin is installed.
 5. If you enabled the Sidebar panel, open the session sidebar and look for `Quota`.
 6. If you enabled Compact status line, look for the home-bottom quota line and the chat/session prompt quota line.
 
@@ -70,8 +70,8 @@ opencode-quota show --provider copilot
 - A `Quota` Sidebar panel in the TUI
 - Popup quota toasts in OpenCode
 - A Compact status line in the TUI
-- `/quota`, `/quota_status`, and `/quota_announcements` slash commands
-- Token reports such as `/tokens_today` and `/tokens_weekly`
+- `/quota`, `/quota_status`, and `/quota_announcements` slash commands when the TUI plugin is installed
+- Token reports such as `/tokens_today` and `/tokens_weekly` when the TUI plugin is installed
 - Provider diagnostics for auth, quota sources, pricing, and bundled maintainer announcements
 
 <table>
@@ -97,7 +97,7 @@ opencode-quota show --provider copilot
   </tr>
   <tr>
     <td width="50%" align="center">Compact status line</td>
-    <td width="50%" align="center"><code>/tokens_weekly</code> report</td>
+    <td width="50%" align="center"><code>/tokens_weekly</code> TUI report</td>
   </tr>
 </table>
 
@@ -111,7 +111,7 @@ Use the installer when possible. For manual setup, use the same OpenCode config
 
 ### 1. Add the server plugin (required)
 
-This enables providers, slash commands, terminal checks, and popup toasts. Add this to `opencode.json` or `opencode.jsonc`:
+This enables providers, terminal checks, popup toasts, and the `tool.quota_status` tool. Add this to `opencode.json` or `opencode.jsonc`:
 
 ```jsonc
 {
@@ -120,9 +120,9 @@ This enables providers, slash commands, terminal checks, and popup toasts. Add t
 }
 ```
 
-### 2. Add the TUI plugin (for Sidebar panel, Compact status line, or announcement home notices)
+### 2. Add the TUI plugin (for dialog slash commands and TUI surfaces)
 
-If you want the Sidebar panel, Compact status line, or maintainer announcement home notices, also add this to `tui.json` or `tui.jsonc`:
+Add this to `tui.json` or `tui.jsonc` for `/quota`, `/quota_status`, `/quota_announcements`, `/pricing_refresh`, `/tokens_*` dialog slash commands, the Sidebar panel, Compact status line, and maintainer announcement home notices:
 
 ```jsonc
 {
@@ -159,7 +159,7 @@ Start with this, then adjust the UI choices in the next section:
 ```
 
 > [!TIP]
-> Run `/quota_status` to see the exact config paths OpenCode Quota loaded.
+> When the TUI plugin is installed, run `/quota_status` to see the exact config paths OpenCode Quota loaded.
 
 ## Choose your UI surfaces
 
@@ -171,7 +171,8 @@ All UI surfaces use the same quota data. Put these settings in `opencode-quota/q
 | Toast | `enableToast: true` | Popup toast after idle/question/compact events. Requires the server plugin entry above. |
 | Compact status line | `tuiCompactStatus.enabled: true` | Short text-only quota line at the home bottom and chat/session prompt locations, for example `Copilot 94% | OpenAI Pro 5h 100%, 7d 100%`. Requires the TUI plugin entry above. |
 | Maintainer announcement notice | `maintainerAnnouncements.enabled: true`, `maintainerAnnouncements.home: true` | Prefers the TUI home notice when the quota TUI plugin is configured. Without the TUI plugin, shows the same count-only notice once after the first visible quota toast. |
-| Terminal/slash only | `enableToast: false`, `tuiSidebarPanel.enabled: false`, `tuiCompactStatus.enabled: false`, `maintainerAnnouncements.enabled: false` | Keeps `/quota`, `/quota_status`, `/quota_announcements`, and terminal checks. |
+| Dialog slash commands | TUI plugin entry in `tui.json` | `/quota`, `/quota_status`, `/quota_announcements`, `/pricing_refresh`, and `/tokens_*` open local TUI dialogs. They do not call the model and do not write command output to the OpenCode session transcript. |
+| Terminal command only | `enableToast: false`, `tuiSidebarPanel.enabled: false`, `tuiCompactStatus.enabled: false`, `maintainerAnnouncements.enabled: false` | Keeps `opencode-quota show` terminal checks while hiding optional toast/sidebar/compact/home surfaces. Does not install TUI slash-command dialogs. |
 
 Selecting Compact status line in the installer enables both compact surfaces by default. To keep compact status home-only, set `tuiCompactStatus.sessionPrompt: false`.
 
@@ -181,9 +182,13 @@ For more examples, see [Common configuration](#common-configuration). For every
 
 ## Commands
 
+Slash commands require the TUI plugin entry in `tui.json` and open deterministic local dialogs. The installer adds that entry only when you select Sidebar or Compact status. They do not invoke a model and do not write command output into the OpenCode session transcript. Session-scoped token commands require an active TUI session.
+
 | Command | What it shows |
 | --- | --- |
 | `opencode-quota show` | Terminal quota-only quick glance |
+| `opencode-quota show --json` | Machine-readable JSON output for external tools |
+| `opencode-quota show --json --threshold <pct>` | Exit `1` if cached quota is below `<pct>%`; exit `2` if none can be compared |
 | `/quota` | Detailed quota report |
 | `/quota_status` | Config, provider, auth, pricing, `enabled`/`home` announcement config, `source=bundled_only`, `network=false`, and active/future/expired announcement counts |
 | `/quota_announcements` | List active bundled maintainer notices |
@@ -201,27 +206,27 @@ For more examples, see [Common configuration](#common-configuration). For every
 
 Most providers work automatically. If a provider has a “Needs setup” link, open that setup note only if you use that provider.
 
-| Provider | Setup | Quota source |
-| --- | --- | --- |
-| Anthropic (Claude) | [Needs setup](#anthropic-claude) | Local CLI or OAuth usage |
-| GitHub Copilot | Usually automatic | Remote API |
-| OpenAI | Automatic | Remote API |
-| Cursor | [Needs setup](#cursor) | Local estimation |
-| Qwen Code | [Needs setup](#qwen-code) | Local estimation |
-| Alibaba Coding Plan | Automatic | Local estimation |
-| MiniMax Coding Plan | Automatic | Remote API |
-| MiniMax Coding Plan (CN) | Automatic | Remote API |
-| Kimi Code | Automatic | Remote API |
-| Chutes AI | Usually automatic | Remote API |
-| Crof.ai | Manual env/config/auth | Remote API |
-| Synthetic | Automatic | Remote API |
-| Google Antigravity | [Needs setup](#google-antigravity) | Remote API |
-| Gemini CLI | [Needs setup](#gemini-cli) | Remote API |
-| Z.ai Coding Plan | Automatic | Remote API |
-| Zhipu Coding Plan | Automatic | Remote API |
-| NanoGPT | Usually automatic | Remote API |
-| DeepSeek | Usually automatic | Remote API balance |
-| OpenCode Go | [Needs setup](#opencode-go) | Dashboard scraping |
+| Provider | Auth/setup | Source | Reports |
+| --- | --- | --- | --- |
+| Anthropic (Claude) | [Needs setup](#anthropic-claude) | Local CLI/OAuth | Usage/quota |
+| GitHub Copilot | OpenCode OAuth or PAT | Remote API | Quota/usage |
+| OpenAI | Automatic | Remote API | Usage/quota |
+| Cursor | [Needs setup](#cursor) | Local estimate | Estimated quota |
+| Qwen Code | [Needs setup](#qwen-code) | Local estimate | Estimated quota |
+| Alibaba Coding Plan | OpenCode config | Local estimate | Estimated quota |
+| MiniMax Coding Plan | OpenCode config | Remote API | Usage/quota |
+| MiniMax Coding Plan (CN) | OpenCode config | Remote API | Usage/quota |
+| Kimi Code | OpenCode config | Remote API | Usage/quota |
+| Chutes AI | API key/config | Remote API | Usage/quota |
+| Synthetic | Automatic | Remote API | Quota |
+| Google Antigravity | [Needs setup](#google-antigravity) | Remote API | Usage/quota |
+| Gemini CLI | [Needs setup](#gemini-cli) | Remote API | Usage/quota |
+| Z.ai Coding Plan | OpenCode config | Remote API | Usage/quota |
+| Zhipu Coding Plan | OpenCode config | Remote API | Usage/quota |
+| NanoGPT | API key/config | Remote APIs | Usage + balance |
+| DeepSeek | API key/config | Remote API | Balance/status |
+| Ollama Cloud | [Needs setup](#ollama-cloud) | Dashboard scraping | Dashboard usage |
+| OpenCode Go | [Needs setup](#opencode-go) | Dashboard scraping | Dashboard usage |
 
 ## Common configuration
 
@@ -233,11 +238,11 @@ Common locations:
 - Global install: usually `~/.config/opencode/opencode-quota/quota-toast.json`
 - Custom config dir: `$OPENCODE_CONFIG_DIR/opencode-quota/quota-toast.json`
 
-If you are unsure, run `/quota_status`; it prints the config path it loaded.
+If you are unsure and the TUI plugin is installed, run `/quota_status`; otherwise check the install-scope paths above.
 
 ### Maintainer announcements and privacy
 
-Announcements are bundled only: no remote fetches, announcement telemetry, or persisted dismiss state. Use `/quota_announcements` to read active notices and `/quota_status` for counts/diagnostics. See **Configure maintainer announcements** below for options.
+Announcements are bundled only: no remote fetches, announcement telemetry, or persisted dismiss state. When the TUI plugin is installed, use `/quota_announcements` to read active notices and `/quota_status` for counts/diagnostics. See **Configure maintainer announcements** below for options.
 
 <details>
 <summary><strong>Choose providers explicitly</strong></summary>
@@ -275,7 +280,7 @@ Announcements are bundled only: no remote fetches, announcement telemetry, or pe
 <details>
 <summary><strong>Turn off popup toasts</strong></summary>
 
-Keeps `/quota`, `/quota_status`, terminal checks, and any enabled UI surfaces.
+Keeps terminal checks, any enabled UI surfaces, and `/quota`/`/quota_status` when the TUI plugin is installed.
 
 ```jsonc
 {
@@ -297,14 +302,14 @@ Keeps `/quota`, `/quota_status`, terminal checks, and any enabled UI surfaces.
 }
 ```
 
-Set `enabled: false` to disable automatic announcement surfaces. `/quota_announcements` lists active bundled notices when announcements are enabled.
+Set `enabled: false` to disable automatic announcement surfaces. When the TUI plugin is installed, `/quota_announcements` lists active bundled notices while announcements are enabled.
 
 </details>
 
 <details>
 <summary><strong>Turn off the Sidebar panel</strong></summary>
 
-Useful when you want Compact status line only, toasts only, or slash commands only.
+Useful when you want Compact status line only, toasts only, or installed TUI slash dialogs without the Sidebar panel.
 
 ```jsonc
 {
@@ -344,6 +349,21 @@ Useful when you want the compact line on the home screen but not in the chat/ses
 
 </details>
 
+<details>
+<summary><strong>Write quota export file</strong></summary>
+
+Writes a JSON file after each TUI background refresh for consumption by external tools (tmux, scripts, CI). See [External integration](#external-integration).
+
+```jsonc
+{
+  "export": {
+    "enabled": true,
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><strong>Advanced: legacy config sync</strong></summary>
 
@@ -370,22 +390,22 @@ Existing `experimental.quotaToast` settings still work when no sidecar file exis
 
 | Option | Default | Meaning |
 | --- | --- | --- |
-| `enabled` | `true` | Master switch for quota collection and handled slash commands. When `false`, `/quota`, `/quota_status`, `/pricing_refresh`, and `/tokens_*` are handled as no-ops. |
+| `enabled` | `true` | Master switch for quota collection and handled slash commands when the TUI plugin is installed. When `false`, `/quota`, `/quota_status`, `/pricing_refresh`, and `/tokens_*` are handled as no-ops. |
 | `enabledProviders` | `"auto"` | Auto-detect providers, or set an explicit provider list. |
 | `minIntervalMs` | `300000` | Minimum fetch interval between provider updates. |
 | `requestTimeoutMs` | `5000` | Remote provider request timeout in milliseconds. |
-| `formatStyle` | `singleWindow` | Shared quota reset-period display for popup toasts and the Sidebar panel: `singleWindow` shows one reset period per provider; `allWindows` shows all reset periods per provider. Legacy `classic`/`grouped` aliases are still accepted. |
-| `percentDisplayMode` | `remaining` | Shared quota percentage meaning for popup toasts and the Sidebar panel: `remaining` shows quota left; `used` shows quota consumed. `/quota` keeps its existing remaining-percent output. |
+| `formatStyle` | `singleWindow` | Shared quota reset-period display for popup toasts, the Sidebar panel, and Compact status line unless a TUI surface override is set: `singleWindow` shows one reset period per provider; `allWindows` shows all reset periods per provider. Legacy `classic`/`grouped` aliases are still accepted. |
+| `percentDisplayMode` | `remaining` | Shared quota percentage meaning for popup toasts, the Sidebar panel, and `/quota` when the TUI plugin is installed: `remaining` shows quota left; `used` shows quota consumed. |
 | `onlyCurrentModel` | `false` | Filter quota rows to the current model/provider when that session selection can be resolved. |
 | `showSessionTokens` | `true` | Show the `Session input/output tokens` section when session token data is available. When cached input is present, the section keeps the legacy `in/out` layout and appends cached input in parentheses next to the input amount. |
-| `pricingSnapshot.source` | `"auto"` | Token pricing snapshot selection for `/tokens_*`: `auto`, `bundled`, or `runtime`. |
+| `pricingSnapshot.source` | `"auto"` | Token pricing snapshot selection for `/tokens_*` when the TUI plugin is installed: `auto`, `bundled`, or `runtime`. |
 | `pricingSnapshot.autoRefresh` | `7` | Refresh stale local pricing data after this many days. |
 
 ### Toast settings
 
 | Option | Default | Meaning |
 | --- | --- | --- |
-| `enableToast` | `true` | Show popup toasts. Disabling this does not disable `/quota` or UI surfaces. |
+| `enableToast` | `true` | Show popup toasts. Disabling this does not disable terminal checks, UI surfaces, or `/quota` when the TUI plugin is installed. |
 | `toastDurationMs` | `9000` | Toast duration in milliseconds. |
 | `showOnIdle` | `true` | Show a toast on the idle trigger. |
 | `showOnQuestion` | `true` | Show a toast after a question/assistant response. |
@@ -401,11 +421,13 @@ Existing `experimental.quotaToast` settings still work when no sidecar file exis
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `tuiSidebarPanel.enabled` | `true` | Show the Sidebar `Quota` panel when the TUI plugin is installed. Click the panel header to toggle between compact summary and detailed all-windows views; OpenCode remembers the last state. |
+| `tuiSidebarPanel.formatStyle` | (root `formatStyle`) | Override `formatStyle` for the Sidebar panel only. Useful when you want `allWindows` detail in the sidebar but a different style elsewhere. |
 | `tuiCompactStatus.enabled` | `false` | Opt in to Compact status line UI surfaces. |
 | `tuiCompactStatus.homeBottom` | `true` | Show the Compact status line at the home bottom location. |
 | `tuiCompactStatus.sessionPrompt` | `true` | Show the Compact status line by wrapping the TUI session prompt. Disable this if you only want the home-bottom line. |
 | `tuiCompactStatus.suppressWhenNativeProviderQuota` | `true` | Hide the Compact status line when OpenCode exposes native provider-quota support. |
 | `tuiCompactStatus.maxWidth` | `96` | Maximum Compact status line text width. |
+| `tuiCompactStatus.formatStyle` | (root `formatStyle`) | Override `formatStyle` for the Compact status line only. Useful when you want `singleWindow` on the compact line while the sidebar shows `allWindows`. |
 
 ### Maintainer announcement settings
 
@@ -426,8 +448,152 @@ Existing `experimental.quotaToast` settings still work when no sidecar file exis
 | `cursorIncludedApiUsd` | unset | Override Cursor monthly included API budget in USD. |
 | `cursorBillingCycleStartDay` | unset | Local billing-cycle anchor day `1..28`; when unset, Cursor usage resets on the local calendar month. |
 
+### Export settings
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `export.enabled` | `false` | Write a JSON export file after each TUI background refresh. |
+| `export.path` | `""` | Export file path. Empty string uses the XDG default: `$XDG_CACHE_HOME/opencode/quota-export.json`. Supports `~/` expansion. |
+
 </details>
 
+## External integration
+
+Quota data is available to external tools via two surfaces that emit the same JSON schema. Both read from the per-provider disk cache — no extra network requests.
+
+### CLI: `show --json`
+
+```
+opencode-quota show --json [--threshold <pct>] [--provider <id>]
+```
+
+| Flag | Behavior |
+|---|---|
+| `--json` | Emit JSON to stdout instead of human-readable text. Reads from the disk cache only — no network calls |
+| `--provider <id>` | Include only one provider key, using the same provider IDs accepted by `show` |
+| `--threshold <pct>` | With `--json`, exit `1` if any comparable cached percentage is below `<pct>`% remaining; exit `2` if there is no cached percentage to compare |
+
+`--json` reads from the per-provider disk cache populated by normal quota refreshes. If no cached entry exists for a provider, that provider is reported as `unavailable`.
+
+### Export file (TUI background writer)
+
+When enabled, the TUI writes a unified JSON file after each home-bottom background refresh (same 60 s interval). The export writer reads the existing provider cache and does not fetch quota itself.
+
+```jsonc
+// opencode-quota/quota-toast.json
+{
+  "export": {
+    "enabled": true,
+    "path": ""  // XDG cache default: $XDG_CACHE_HOME/opencode/quota-export.json
+  }
+}
+```
+
+The file is written atomically. Write errors are logged as a warning and never affect TUI rendering.
+
+### JSON schema
+
+Both surfaces emit the same structure:
+
+```jsonc
+{
+  "version": 1,
+  "exportedAt": 1748736000,       // unix seconds
+  "fromCache": true,
+  "cacheAgeSeconds": 42,          // age of the oldest provider entry
+  "providers": {
+    "copilot": {
+      "status": "ok",
+      "fetchedAt": 1748735958,
+      "entries": [
+        {
+          "name": "Premium Requests",
+          "window": "Monthly",
+          "percentRemaining": 62.3,
+          "resetAt": 1748908800,
+          "unlimited": false
+        }
+      ]
+    },
+    "opencode-go": {
+      "status": "error",
+      "fetchedAt": 1748735958,
+      "error": "Request timeout after 5000ms"
+    },
+    "anthropic": {
+      "status": "unavailable"     // no cached quota is available
+    }
+  }
+}
+```
+
+Provider `status` values:
+
+| Value | Meaning |
+|---|---|
+| `ok` | Cached fetch succeeded; `entries` is populated |
+| `error` | Cached fetch was attempted but failed; `error` has the message |
+| `unavailable` | No cached quota is available, such as missing credentials or no prior refresh |
+
+Optional fields: `window` is present only when a provider row reports one, `percentRemaining` is absent for value-only rows, and `resetAt` is absent when the provider does not report a reset time.
+
+### Integration examples
+
+**CI gate — abort if quota is low:**
+```bash
+npx @slkiser/opencode-quota show --json --threshold 5
+# exits 1 if any comparable cached provider is below 5% remaining
+# exits 2 if there is no cached percentage to compare
+```
+
+**Shell script — branch on remaining quota:**
+```bash
+PCT=$(opencode-quota show --json | jq '.providers["copilot"].entries[0].percentRemaining')
+(( ${PCT%.*} < 10 )) && echo "Low quota, skipping." && exit 0
+```
+
+**tmux status-right — reads export file (no subprocess per refresh):**
+```bash
+# ~/.tmux.conf
+set -g status-interval 30
+set -g status-right '#(jq -r "[.providers|to_entries[]|select(.value.status==\"ok\")|(.value.entries[0].percentRemaining|floor|tostring)+\"%\"]|join(\" · \")" ~/.cache/opencode/quota-export.json 2>/dev/null)'
+```
+
+**Starship prompt — reads cache directly (no TUI needed):**
+```toml
+# starship.toml
+[custom.quota]
+command = "opencode-quota show --json 2>/dev/null | jq -r '[.providers|to_entries[]|select(.value.status==\"ok\")|(.value.entries[0].percentRemaining|floor|tostring)+\"%\"]|join(\" \")'"
+when = "true"
+interval = 60
+```
+
+**File-watch push — event-driven, zero polling:**
+```bash
+# macOS
+fswatch -o ~/.cache/opencode/quota-export.json | xargs -I{} my-status-refresh
+
+# Linux
+inotifywait -m -e close_write ~/.cache/opencode/quota-export.json \
+  | while read; do my-status-refresh; done
+```
+
+**LLM proxy router — pick the provider with the most headroom:**
+```python
+import json, subprocess
+
+data = json.loads(subprocess.check_output(
+    ["opencode-quota", "show", "--json"], timeout=1
+))
+best = max(
+    (k for k, v in data["providers"].items() if v["status"] == "ok"),
+    key=lambda k: next(
+        (e.get("percentRemaining", 0) for e in data["providers"][k]["entries"]), 0
+    ),
+    default=None,
+)
+```
+
 ## Provider setup notes
 
 <a id="anthropic-claude"></a>
@@ -515,6 +681,25 @@ If you use manual provider selection, include `deepseek` in `enabledProviders`.
 
 </details>
 
+<a id="ollama-cloud"></a>
+<details>
+<summary><strong>Ollama Cloud</strong></summary>
+
+Ollama Cloud quota scrapes the Ollama Cloud settings page and needs a `__Secure-session` cookie:
+
+```bash
+export OLLAMA_USAGE_COOKIE="your-session-cookie-value"
+```
+
+Or use one of these config files (cookie without the `__Secure-session=` prefix, or with — the plugin normalizes it):
+
+- `~/.config/opencode/opencode-quota/ollama-cloud.json`: `{ "cookie": "..." }`
+- `~/.config/ollama-usage/config.yaml`: `cookie: "..."`
+
+To find the cookie, open `ollama.com/settings` in your browser, open Developer Tools → Storage → Cookies, and copy the value of `__Secure-session`.
+
+</details>
+
 <a id="opencode-go"></a>
 <details>
 <summary><strong>OpenCode Go</strong></summary>
@@ -534,7 +719,7 @@ Use `opencodeGoWindows` to choose **5h**, **Weekly**, and/or **Monthly** windows
 
 Start here when quota or token data looks wrong.
 
-1. Run `/quota_status`.
+1. When the TUI plugin is installed, run `/quota_status`; otherwise start with `opencode-quota show` for a terminal quota summary.
 2. Confirm the expected provider appears in the detected provider list.
 3. Confirm companion auth plugins are before `@slkiser/opencode-quota` in `opencode.json`.
 4. If token reports are empty, start OpenCode once so it creates `opencode.db`, then run a session with model usage.
@@ -544,28 +729,30 @@ Start here when quota or token data looks wrong.
 
 | Symptom | Try this |
 | --- | --- |
-| `/quota` shows no providers | Run `/quota_status`, then check provider detection and auth. |
+| `/quota` or other slash commands do not appear | Confirm `tui.json` includes `@slkiser/opencode-quota`, then restart OpenCode. |
+| `/quota` shows no providers | Run `/quota_status` when the TUI plugin is installed, then check provider detection and auth. Without the TUI plugin, use `opencode-quota show` for a terminal quota summary. |
 | Sidebar panel does not appear | Confirm `tui.json` includes `@slkiser/opencode-quota`, restart OpenCode, and check `tuiSidebarPanel.enabled`. |
 | Compact status line does not appear anywhere | Confirm `tui.json` includes `@slkiser/opencode-quota`, restart OpenCode, check `tuiCompactStatus.enabled`, and check whether `tuiCompactStatus.suppressWhenNativeProviderQuota` is hiding it because OpenCode exposes native provider-quota support. |
 | Compact status appears on home but not in chat/session | Check `tuiCompactStatus.sessionPrompt`; set it to `true` to show the chat/session prompt line. |
 | Popup toasts do not appear | Check `enableToast`, `showOnIdle`, `showOnQuestion`, and `showOnCompact`. |
-| Announcement home notice does not appear | Confirm `tui.json` includes `@slkiser/opencode-quota`, restart OpenCode, then check `maintainerAnnouncements.enabled`, `maintainerAnnouncements.home`, and the active count in the `maintainer_announcements` section of `/quota_status`. |
+| Announcement home notice does not appear | Confirm `tui.json` includes `@slkiser/opencode-quota`, restart OpenCode, then check `maintainerAnnouncements.enabled`, `maintainerAnnouncements.home`, and, when the TUI plugin is installed, the active count in the `maintainer_announcements` section of `/quota_status`. |
 | Token reports are empty | Start OpenCode once so `opencode.db` exists, then run a session with model usage. |
-| Pricing looks stale | Run `/pricing_refresh`. |
+| Pricing looks stale | Run `/pricing_refresh` when the TUI plugin is installed. |
+| `/tokens_between` needs dates | When the TUI plugin is installed, run `/tokens_between YYYY-MM-DD YYYY-MM-DD`; if your OpenCode build does not pass slash arguments to TUI commands, the dialog shows the expected format. |
 
 ### Provider troubleshooting
 
 <details>
 <summary><strong>Anthropic (Claude)</strong></summary>
 
-Run `/quota_status` and check the Anthropic section.
+When the TUI plugin is installed, run `/quota_status` and check the Anthropic section.
 
 | Symptom | Fix |
 | --- | --- |
 | `claude` not found | Install Claude Code and make sure `claude` is on your `PATH`. |
 | Claude is installed at a custom path | Set `anthropicBinaryPath` in `opencode-quota/quota-toast.json`. |
 | Not authenticated | Run `claude auth login`, then confirm `claude auth status` works. |
-| Auth works but no quota rows appear | Check `quota_source` and `message` in `/quota_status`; re-authenticate Claude if the OAuth credential fallback is missing or stale. |
+| Auth works but no quota rows appear | When the TUI plugin is installed, check `quota_source` and `message` in `/quota_status`; re-authenticate Claude if the OAuth credential fallback is missing or stale. |
 | Provider not detected | Confirm OpenCode is configured to use the `anthropic` provider. |
 
 </details>
@@ -573,7 +760,7 @@ Run `/quota_status` and check the Anthropic section.
 <details>
 <summary><strong>GitHub Copilot</strong></summary>
 
-Run `/quota_status` and check `copilot_quota_auth`, `billing_mode`, `billing_scope`, and `quota_api`.
+When the TUI plugin is installed, run `/quota_status` and check `copilot_quota_auth`, `billing_mode`, `billing_scope`, and `quota_api`.
 
 | Symptom | Fix |
 | --- | --- |
@@ -587,7 +774,7 @@ Run `/quota_status` and check `copilot_quota_auth`, `billing_mode`, `billing_sco
 <details>
 <summary><strong>OpenAI</strong></summary>
 
-Run `/quota_status` and check the OpenAI auth source and token status.
+When the TUI plugin is installed, run `/quota_status` and check the OpenAI auth source and token status.
 
 | Symptom | Fix |
 | --- | --- |
@@ -600,7 +787,7 @@ Run `/quota_status` and check the OpenAI auth source and token status.
 <details>
 <summary><strong>Cursor</strong></summary>
 
-Run `/quota_status` and check the Cursor section.
+When the TUI plugin is installed, run `/quota_status` and check the Cursor section.
 
 | Symptom | Fix |
 | --- | --- |
@@ -608,42 +795,42 @@ Run `/quota_status` and check the Cursor section.
 | Cursor auth missing | Run `opencode auth login --provider cursor`. |
 | Quota appears but no remaining percentage | Set `cursorPlan` or `cursorIncludedApiUsd` in `opencode-quota/quota-toast.json`. |
 | Billing cycle looks wrong | Set `cursorBillingCycleStartDay` in `opencode-quota/quota-toast.json` to your local billing anchor day. |
-| Unknown Cursor pricing | Run `/pricing_refresh`; if still unknown, check `/quota_status` for unknown model ids. |
+| Unknown Cursor pricing | Run `/pricing_refresh` when the TUI plugin is installed; if still unknown, check `/quota_status` for unknown model ids. |
 
 </details>
 
 <details>
 <summary><strong>Qwen Code</strong></summary>
 
-Run `/quota_status` and check `qwen_oauth_source`, `qwen_local_plan`, and the `qwen_code` live probe section.
+When the TUI plugin is installed, run `/quota_status` and check `qwen_oauth_source`, `qwen_local_plan`, and the `qwen_code` live probe section.
 
 | Symptom | Fix |
 | --- | --- |
 | Qwen not detected | Put `opencode-qwencode-auth` before `@slkiser/opencode-quota` in `opencode.json`. |
 | Auth missing | Complete the Qwen companion plugin auth flow. |
 | Counters do not move | Confirm the current model is `qwen-code/*`; Qwen quota is local request estimation for matching model usage. |
-| Usage looks stale | Check the local state file path shown by `/quota_status`. |
+| Usage looks stale | When the TUI plugin is installed, check the local state file path shown by `/quota_status`. |
 
 </details>
 
 <details>
 <summary><strong>Alibaba Coding Plan</strong></summary>
 
-Run `/quota_status` and check the Alibaba auth, resolved tier, state-file path, and `alibaba_coding_plan` live probe section.
+When the TUI plugin is installed, run `/quota_status` and check the Alibaba auth, resolved tier, state-file path, and `alibaba_coding_plan` live probe section.
 
 | Symptom | Fix |
 | --- | --- |
 | API key not detected | Use `ALIBABA_CODING_PLAN_API_KEY`, `ALIBABA_API_KEY`, trusted user/global OpenCode config, or OpenCode auth. Repo-local provider secrets are ignored. |
 | Wrong tier | Set `alibabaCodingPlanTier` to `lite` or `pro` in `opencode-quota/quota-toast.json`. |
 | Counters do not move | Confirm the current model is `alibaba/*` or `alibaba-cn/*`. |
-| Quota seems stale | Check the state-file path shown in `/quota_status`. |
+| Quota seems stale | When the TUI plugin is installed, check the state-file path shown in `/quota_status`. |
 
 </details>
 
 <details>
-<summary><strong>MiniMax, Kimi, Chutes AI, Crof.ai, Synthetic, Z.ai, Zhipu, NanoGPT, and DeepSeek</strong></summary>
+<summary><strong>MiniMax, Kimi, Chutes AI, Synthetic, Z.ai, Zhipu, NanoGPT, and DeepSeek</strong></summary>
 
-These providers use trusted env vars, trusted user/global OpenCode config, or native OpenCode auth. Run `/quota_status` and check the provider-specific API-key diagnostics.
+These providers use trusted env vars, trusted user/global OpenCode config, or native OpenCode auth. When the TUI plugin is installed, run `/quota_status` and check the provider-specific API-key diagnostics.
 
 | Provider | Useful checks |
 | --- | --- |
@@ -651,7 +838,6 @@ These providers use trusted env vars, trusted user/global OpenCode config, or na
 | MiniMax Coding Plan (CN) | Use `MINIMAX_CHINA_CODING_PLAN_API_KEY` or trusted user/global OpenCode config under `minimax-china-coding-plan`, `minimax-cn-coding-plan`, `minimax-cn`, or `minimax-china`. Runtime id `minimax-cn-coding-plan` uses this provider. |
 | Kimi Code | Use `KIMI_API_KEY` or `KIMI_CODE_API_KEY`; repo-local provider secrets are ignored. |
 | Chutes AI | Use `CHUTES_API_KEY`, trusted user/global config, or OpenCode auth. |
-| Crof.ai | Use `CROF_API_KEY`, `CROFAI_API_KEY`, trusted user/global config, or OpenCode auth. |
 | Synthetic | Use `SYNTHETIC_API_KEY`, trusted user/global config, or OpenCode auth. |
 | Z.ai Coding Plan | Use `ZAI_API_KEY` or `ZAI_CODING_PLAN_API_KEY`; malformed fallback auth is surfaced as an auth error. |
 | Zhipu Coding Plan | Use `ZHIPU_API_KEY` or `ZHIPU_CODING_PLAN_API_KEY`; malformed fallback auth is surfaced as an auth error. |
@@ -665,21 +851,21 @@ For security, repo-local `opencode.json` / `opencode.jsonc` is ignored for provi
 <details>
 <summary><strong>Google Antigravity</strong></summary>
 
-Run `/quota_status` and check the `google_antigravity` section.
+When the TUI plugin is installed, run `/quota_status` and check the `google_antigravity` section.
 
 | Symptom | Fix |
 | --- | --- |
 | Companion missing | Put `opencode-antigravity-auth` before `@slkiser/opencode-quota` in `opencode.json`. |
-| Accounts not found | Check the selected `antigravity-accounts.json` path shown by `/quota_status`. |
+| Accounts not found | When the TUI plugin is installed, check the selected `antigravity-accounts.json` path shown by `/quota_status`. |
 | Refresh tokens invalid | Re-authenticate with the companion plugin. |
-| Provider returns no rows | Check `live_probe`, `live_entry_*`, and `live_error_*` in `/quota_status`. |
+| Provider returns no rows | When the TUI plugin is installed, check `live_probe`, `live_entry_*`, and `live_error_*` in `/quota_status`. |
 
 </details>
 
 <details>
 <summary><strong>Gemini CLI</strong></summary>
 
-Run `/quota_status` and check the Gemini CLI live probe rows.
+When the TUI plugin is installed, run `/quota_status` and check the Gemini CLI live probe rows.
 
 | Symptom | Fix |
 | --- | --- |
@@ -693,14 +879,14 @@ Run `/quota_status` and check the Gemini CLI live probe rows.
 <details>
 <summary><strong>OpenCode Go</strong></summary>
 
-Run `/quota_status` and check the `opencode_go` section.
+When the TUI plugin is installed, run `/quota_status` and check the `opencode_go` section.
 
 | Symptom | Fix |
 | --- | --- |
-| Config not detected | Set both `OPENCODE_GO_WORKSPACE_ID` and `OPENCODE_GO_AUTH_COOKIE`, then rerun `/quota_status`. |
+| Config not detected | Set both `OPENCODE_GO_WORKSPACE_ID` and `OPENCODE_GO_AUTH_COOKIE`, then rerun `/quota_status` when the TUI plugin is installed. |
 | Incomplete config | `workspaceId` and `authCookie` must come from the same source. |
 | Scrape returns no data | Refresh the browser `auth` cookie from `opencode.ai`. |
-| Selected window missing | Check `/quota_status` for `selected_windows` and `live_fetch_error`; remove unavailable windows from `opencodeGoWindows` in `opencode-quota/quota-toast.json` or refresh the dashboard cookie. |
+| Selected window missing | When the TUI plugin is installed, check `/quota_status` for `selected_windows` and `live_fetch_error`; remove unavailable windows from `opencodeGoWindows` in `opencode-quota/quota-toast.json` or refresh the dashboard cookie. |
 | Dashboard format changed | This integration scrapes the dashboard, so it can break if the dashboard markup changes. |
 
 </details>
@@ -708,14 +894,14 @@ Run `/quota_status` and check the `opencode_go` section.
 <details>
 <summary><strong>Token reports</strong></summary>
 
-Run `/quota_status` and check pricing snapshot health plus OpenCode database paths.
+When the TUI plugin is installed, run `/quota_status` and check pricing snapshot health plus OpenCode database paths.
 
 | Symptom | Fix |
 | --- | --- |
 | `/tokens_*` is empty | Start OpenCode once so it creates `opencode.db`, then run a session with model usage. |
-| Pricing looks stale | Run `/pricing_refresh`. |
+| Pricing looks stale | Run `/pricing_refresh` when the TUI plugin is installed. |
 | Runtime pricing does not change output | Check `pricingSnapshot.source` in `opencode-quota/quota-toast.json`; `bundled` keeps packaged pricing active. |
-| Cursor model has unknown pricing | Run `/pricing_refresh`; Cursor `auto` and `composer*` use bundled deterministic pricing. |
+| Cursor model has unknown pricing | Run `/pricing_refresh` when the TUI plugin is installed; Cursor `auto` and `composer*` use bundled deterministic pricing. |
 
 </details>
 

package/dist/bin/opencode-quota.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-quota.d.ts","sourceRoot":"","sources":["../../src/bin/opencode-quota.ts"],"names":[],"mappings":";AAgCA,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,GAAG,SAA2B,EAC3C,UAAU,GAAE,MAAuC,EACnD,WAAW,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAuB,GACzD,OAAO,CAMT;AAED,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BxE"}
+{"version":3,"file":"opencode-quota.d.ts","sourceRoot":"","sources":["../../src/bin/opencode-quota.ts"],"names":[],"mappings":";AAmCA,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,GAAG,SAA2B,EAC3C,UAAU,GAAE,MAAuC,EACnD,WAAW,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAuB,GACzD,OAAO,CAMT;AAED,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BxE"}

package/dist/bin/opencode-quota.js

@@ -6,13 +6,16 @@ import { runInitInstaller } from "../lib/init-installer.js";
 const USAGE = [
     "Usage:",
     "  npx @slkiser/opencode-quota init [--sync-legacy-config]",
-    "  npx @slkiser/opencode-quota show [--provider <provider-id>]",
+    "  npx @slkiser/opencode-quota show [--provider <provider-id>] [--json] [--threshold <pct>]",
     "  npx @slkiser/opencode-quota --help",
     "",
     "Commands:",
     "  init    Run the interactive quota installer",
     "          --sync-legacy-config also writes experimental.quotaToast",
     "  show    Print a quick quota glance",
+    "          --json               Machine-readable JSON output (reads from cache)",
+    "          --threshold <pct>    With --json, exit 1 if below <pct>%, 2 if no cached quota",
+    "          --provider <id>      Filter to one provider",
 ].join("\n");
 function printUsage() {
     console.log(USAGE);