opencode-copilot-budget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-copilot-budget contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# opencode-copilot-budget
+
+Shows your GitHub Copilot premium request budget in the [OpenCode](https://opencode.ai) TUI sidebar. Only visible when the active provider is `github-copilot`.
+
+![Preview](assets/preview.png)
+
+## Features
+
+- Progress bar that turns **red** when you reach 90 % of your budget
+- Request count and percentage used
+- Reset date, updated automatically after every AI response
+- 5-minute cache to avoid unnecessary API calls
+- Works with paid and free Copilot plans
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) with `github-copilot` as your active provider
+- A GitHub token via one of:
+  - `GITHUB_TOKEN` or `GH_TOKEN` environment variable
+  - [GitHub CLI](https://cli.github.com) (`gh auth login`)
+
+## Install
+
+### Option A — OpenCode plugin manager
+
+```bash
+opencode plugin opencode-copilot-budget
+```
+
+This installs the plugin and adds it to your `~/.config/opencode/tui.json` automatically.
+
+### Option B — manual
+
+Add to `~/.config/opencode/tui.json` (create the file if it doesn't exist):
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["opencode-copilot-budget"]
+}
+```
+
+### Option C — local path (no npm)
+
+Point OpenCode directly at the source file by absolute path:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["/absolute/path/to/opencode-copilot-budget"]
+}
+```
+
+## Token setup
+
+The plugin discovers your GitHub token in this order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `GH_TOKEN` environment variable
+3. Output of `gh auth token` (GitHub CLI)
+
+If none of the above are available, add the token to your shell profile:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export GITHUB_TOKEN="ghp_your_token_here"
+```
+
+To pull it from the GitHub CLI:
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)
+```
+
+## What it shows
+
+| Situation | Display |
+|---|---|
+| Capped plan | progress bar + `117 / 1000 Premium Requests` |
+| ≥ 90 % used | progress bar turns red |
+| Unlimited plan | `62 used (unlimited)` |
+| Overage consumed | `+5 overage` (shown below usage) |
+| Reset date known | `Resets on 1 May` (date in bold) |
+| Token missing / network error | `sync unavailable` |
+| First load | `syncing...` |
+
+## Uninstall
+
+Remove `opencode-copilot-budget` from the `plugin` array in `~/.config/opencode/tui.json`.
+
+---
+
+## Contributing
+
+All logic lives in a single file — `src/index.tsx` — so it's easy to get started.
+
+### Local development setup
+
+1. Clone the repo:
+
+   ```bash
+   git clone https://github.com/bhaskarmelkani/opencode-copilot-budget
+   cd opencode-copilot-budget
+   npm install
+   ```
+
+2. Point OpenCode at your local clone via an absolute path in `~/.config/opencode/tui.json`:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/tui.json",
+     "plugin": ["/absolute/path/to/opencode-copilot-budget"]
+   }
+   ```
+
+3. Edit `src/index.tsx` and restart OpenCode to see changes.
+
+### Codebase overview
+
+```
+src/index.tsx   — entire plugin: token discovery, API fetch, caching, and UI
+```
+
+| Area | Function / component |
+|---|---|
+| Token discovery | `discoverToken()` |
+| API response parsing (paid + free tiers) | `parseResponse()` |
+| Fetch with 5-minute cache | `fetchCopilotUsage()` |
+| Progress bar | `ProgressBar` |
+| Usage display (SolidJS) | `UsageDetail`, `View` |
+| Plugin registration | bottom of file |
+
+### Submitting changes
+
+- Open an issue first for non-trivial changes so we can align on direction
+- Keep PRs focused — one concern per PR
+- If you add a new display state, update the "What it shows" table above
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "opencode-copilot-budget",
+  "version": "1.0.0",
+  "description": "GitHub Copilot premium budget in the OpenCode TUI sidebar",
+  "author": "Bhaskar Melkani",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bhaskarmelkani/opencode-copilot-budget.git"
+  },
+  "homepage": "https://github.com/bhaskarmelkani/opencode-copilot-budget#readme",
+  "bugs": {
+    "url": "https://github.com/bhaskarmelkani/opencode-copilot-budget/issues"
+  },
+  "type": "module",
+  "exports": {
+    "./tui": "./src/index.tsx"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*",
+    "@opentui/solid": "*",
+    "solid-js": "*"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-tui-plugin",
+    "github-copilot"
+  ],
+  "license": "MIT"
+}

package/src/index.tsx

@@ -0,0 +1,296 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * opencode-copilot-budget
+ *
+ * Displays your GitHub Copilot premium request budget in the OpenCode TUI
+ * sidebar. Automatically refreshes after each AI response. Only visible when
+ * the active provider is `github-copilot`.
+ *
+ * Display format:
+ *   Copilot Budget
+ *   ████████░░░░░░░░ 12% Used      ← green; turns red at ≥ 90 %
+ *   117 / 1000 Premium Requests
+ *   Resets on 1 May
+ *
+ * Token discovery (in priority order):
+ *   1. GITHUB_TOKEN environment variable
+ *   2. GH_TOKEN environment variable
+ *   3. `gh auth token` (GitHub CLI)
+ *
+ * Install:
+ *   opencode plugin opencode-copilot-budget
+ *
+ * Or add manually to ~/.config/opencode/tui.json:
+ *   { "plugin": ["opencode-copilot-budget"] }
+ */
+
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { createMemo, createResource, Match, onCleanup, onMount, Show, Switch } from "solid-js"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+const id = "copilot-budget.sidebar"
+
+const execFileAsync = promisify(execFile)
+
+const COPILOT_USER_ENDPOINT = "https://api.github.com/copilot_internal/user"
+const CACHE_TTL_MS = 5 * 60 * 1000
+const REQUEST_TIMEOUT_MS = 10_000
+const BAR_WIDTH = 16
+const BAR_FILL_COLOR = "#3fb950" // GitHub green
+const BAR_DANGER_COLOR = "#f85149" // red when >= 90%
+
+// VS Code impersonation headers — kept as constants for easy version updates
+const EDITOR_VERSION = "vscode/1.96.2"
+const EDITOR_PLUGIN_VERSION = "copilot-chat/0.26.7"
+const USER_AGENT = "GitHubCopilotChat/0.26.7"
+const GITHUB_API_VERSION = "2026-01-01"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+type CopilotUsageData = {
+  used: number
+  entitlement: number
+  percent: number
+  unlimited: boolean
+  overageCount: number
+  overagePermitted: boolean
+  resetDate: string | null
+  tier: "paid" | "free"
+}
+
+// ─── Cache ───────────────────────────────────────────────────────────────────
+
+type CacheEntry = { data: CopilotUsageData | null; timestamp: number }
+let _cache: CacheEntry | null = null
+
+function bustCache() {
+  _cache = null
+}
+
+// ─── Token Discovery ─────────────────────────────────────────────────────────
+
+async function discoverToken(): Promise<string | null> {
+  // 1. GITHUB_TOKEN — standard env var (CI / devcontainers / manual export)
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN
+
+  // 2. GH_TOKEN — alias used by GitHub CLI and many CI environments
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN
+
+  // 3. GitHub CLI — for users who ran `gh auth login`
+  try {
+    const { stdout } = await execFileAsync("gh", ["auth", "token"], { timeout: 5_000 })
+    const token = stdout.trim()
+    if (token) return token
+  } catch {
+    // gh not installed or not authenticated — silent fallthrough
+  }
+
+  return null
+}
+
+// ─── Response Parsing ────────────────────────────────────────────────────────
+
+function parseResponse(body: unknown): CopilotUsageData | null {
+  if (!body || typeof body !== "object") return null
+  const data = body as Record<string, unknown>
+
+  // Paid tier: quota_snapshots.premium_interactions
+  const snapshots = data.quota_snapshots as Record<string, unknown> | undefined
+  if (snapshots?.premium_interactions && typeof snapshots.premium_interactions === "object") {
+    const pi = snapshots.premium_interactions as Record<string, unknown>
+    const entitlement = Number(pi.entitlement ?? 0)
+    const remaining = Number(pi.remaining ?? 0)
+    const unlimited = Boolean(pi.unlimited)
+    const used = unlimited
+      ? Number(pi.used ?? Math.max(0, entitlement - remaining))
+      : Math.max(0, entitlement - remaining)
+    const percent = unlimited || entitlement === 0 ? 0 : Math.round((used / entitlement) * 100)
+
+    return {
+      used: Math.round(used),
+      entitlement,
+      percent,
+      unlimited,
+      overageCount: Number(pi.overage_count ?? 0),
+      overagePermitted: Boolean(pi.overage_permitted),
+      resetDate: (data.quota_reset_date_utc as string | undefined) ?? null,
+      tier: "paid",
+    }
+  }
+
+  // Free tier: limited_user_quotas or monthly_quotas
+  const luq = data.limited_user_quotas as Record<string, unknown> | undefined
+  const mq = data.monthly_quotas as Record<string, unknown> | undefined
+  if (luq || mq) {
+    const piLuq = (luq?.premium_interactions as Record<string, unknown> | undefined) ?? {}
+    const piMq = (mq?.premium_interactions as Record<string, unknown> | undefined) ?? {}
+    const pi = Object.keys(piLuq).length ? piLuq : piMq
+
+    // Both sources empty — can't derive meaningful usage data
+    if (!Object.keys(pi).length) return null
+
+    const entitlement = Number(pi.entitlement ?? 0)
+    const remaining = Number(pi.remaining ?? 0)
+    const unlimited = Boolean(pi.unlimited)
+    const used = Math.max(0, entitlement - remaining)
+    const percent = unlimited || entitlement === 0 ? 0 : Math.round((used / entitlement) * 100)
+    const resetDate =
+      (data.limited_user_reset_date as string | undefined) ??
+      (data.quota_reset_date_utc as string | undefined) ??
+      null
+
+    return {
+      used: Math.round(used),
+      entitlement,
+      percent,
+      unlimited,
+      overageCount: 0,
+      overagePermitted: false,
+      resetDate,
+      tier: "free",
+    }
+  }
+
+  return null
+}
+
+// ─── Fetch (with caching) ────────────────────────────────────────────────────
+
+async function fetchCopilotUsage(): Promise<CopilotUsageData | null> {
+  if (_cache !== null && Date.now() - _cache.timestamp < CACHE_TTL_MS) {
+    return _cache.data
+  }
+
+  const token = await discoverToken()
+  if (!token) {
+    _cache = { data: null, timestamp: Date.now() }
+    return null
+  }
+
+  try {
+    const response = await fetch(COPILOT_USER_ENDPOINT, {
+      headers: {
+        Authorization: `token ${token}`,
+        Accept: "application/json",
+        // Match the headers sent by VS Code's official Copilot Chat extension.
+        "Editor-Version": EDITOR_VERSION,
+        "Editor-Plugin-Version": EDITOR_PLUGIN_VERSION,
+        "User-Agent": USER_AGENT,
+        "X-Github-Api-Version": GITHUB_API_VERSION,
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    })
+
+    if (!response.ok) {
+      _cache = { data: null, timestamp: Date.now() }
+      return null
+    }
+
+    const body = (await response.json()) as unknown
+    const parsed = parseResponse(body)
+    _cache = { data: parsed, timestamp: Date.now() }
+    return parsed
+  } catch {
+    _cache = { data: null, timestamp: Date.now() }
+    return null
+  }
+}
+
+// ─── UI ──────────────────────────────────────────────────────────────────────
+
+function formatResetDate(dateStr: string): string {
+  try {
+    return new Date(dateStr).toLocaleDateString(undefined, { day: "numeric", month: "long" })
+  } catch {
+    return dateStr
+  }
+}
+
+function ProgressBar(props: { percent: number }) {
+  const clampedPercent = Math.min(100, Math.max(0, props.percent))
+  const filled = Math.round((clampedPercent / 100) * BAR_WIDTH)
+  const empty = BAR_WIDTH - filled
+  const color = clampedPercent >= 90 ? BAR_DANGER_COLOR : BAR_FILL_COLOR
+  return (
+    <text fg={color}>{`${"█".repeat(filled)}${"░".repeat(empty)} ${clampedPercent}% Used`}</text>
+  )
+}
+
+function UsageDetail(props: { api: TuiPluginApi }) {
+  const theme = () => props.api.theme.current
+  const [usage, { refetch }] = createResource(fetchCopilotUsage)
+
+  onMount(() => {
+    // Refetch whenever the AI finishes responding — exactly when a Copilot
+    // request has been consumed. Bust the cache first so we always hit the
+    // network and get a fresh count.
+    const off = props.api.event.on("session.idle", () => {
+      bustCache()
+      refetch()
+    })
+    onCleanup(off)
+  })
+
+  return (
+    <Switch>
+      <Match when={usage()}>
+        {(data) => (
+          <box direction="column">
+            <Show
+              when={!data().unlimited}
+              fallback={<text fg={theme().textMuted}>{`${data().used} used (unlimited)`}</text>}
+            >
+              <ProgressBar percent={data().percent} />
+              <text fg={theme().textMuted}>{`${data().used} / ${data().entitlement} Premium Requests`}</text>
+            </Show>
+            <Show when={data().overageCount > 0}>
+              <text fg={theme().warning}>{`+${data().overageCount} overage`}</text>
+            </Show>
+            <Show when={data().resetDate}>
+              <text fg={theme().textMuted}>{"Resets on "}<b>{formatResetDate(data().resetDate!)}</b></text>
+            </Show>
+          </box>
+        )}
+      </Match>
+      <Match when={usage.loading}>
+        <text fg={theme().textMuted}>syncing...</text>
+      </Match>
+      <Match when={true}>
+        <text fg={theme().textMuted}>sync unavailable</text>
+      </Match>
+    </Switch>
+  )
+}
+
+function View(props: { api: TuiPluginApi }) {
+  const theme = () => props.api.theme.current
+  const isCopilot = createMemo(() =>
+    props.api.state.provider.some((p) => p.id === "github-copilot"),
+  )
+
+  return (
+    <Show when={isCopilot()}>
+      <box direction="column">
+        <text fg={theme().text}><b>Copilot Budget</b></text>
+        <UsageDetail api={props.api} />
+      </box>
+    </Show>
+  )
+}
+
+// ─── Plugin Registration ──────────────────────────────────────────────────────
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    order: 50, // top of sidebar — before Context (100), MCP (200), LSP (300), etc.
+    slots: {
+      sidebar_content() {
+        return <View api={api} />
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = { id, tui }
+export default plugin