opencode-github-copilot-usage

An OpenCode plugin for V1 and V2 that shows your GitHub Copilot usage, in AI credits and percentage, right in the TUI.

Copilot 2,000/15,000 cr · 13.3%

Features

• Usage line below the prompt footer, shown only while a GitHub Copilot model is selected (on V1: when the session's latest message used Copilot).
• Colour changes as you approach your limit: muted below 75%, warning from 75%, error from 90%.
• Refreshes every 15 seconds and shortly after each completed turn.
• /copilot-usage slash command (also in the command palette) with full details: account, plan, billing type, used/remaining, overage, and reset date.
• Settings in the TUI: press ctrl+s in the /copilot-usage dialog to change the poll interval and footer format without editing config.
• Uses the GitHub Copilot login already stored in OpenCode. No extra token needed. GitHub Enterprise logins are supported.

Requirements

• OpenCode V2 (tested with 2.0.28), or OpenCode V1 1.18.29 or newer.
• GitHub Copilot connected in OpenCode.

Install

OpenCode V2

opencode plugin add opencode-github-copilot-usage

Or add it to ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-github-copilot-usage"],
}

OpenCode V1

opencode plugin opencode-github-copilot-usage --global

Or add it to ~/.config/opencode/tui.json:

{
  "plugin": ["opencode-github-copilot-usage"]
}

On V1 the plugin runs only in the TUI. It reads the Copilot login from OpenCode's auth.json and calls GitHub directly. The usage line appears at the bottom of a session when that session's latest message used a GitHub Copilot model.

Options

V2 (opencode.jsonc):

{
  "plugins": [
    {
      "package": "opencode-github-copilot-usage",
      "options": {
        // Poll interval in seconds (minimum 5, default 15)
        "interval": 15,
        // Footer format: "full" (default) shows "Copilot 2,000/15,000 cr · 13.3%",
        // "percent" shows "Copilot 13.3%". /copilot-usage always shows full details.
        "display": "full",
      },
    },
  ],
}

V1 (tui.json):

{
  "plugin": [["opencode-github-copilot-usage", { "interval": 15, "display": "percent" }]]
}

Changing options in the TUI

Run /copilot-usage and press ctrl+s (on V1, pick settings at the end of the list). Change the selected setting with ←/→:

• Footer → Format: full or percent. enter also toggles it.
• Refresh → Interval: 15, 30, 60 or 120 seconds. Press enter for a custom value of 5 or more.
• ctrl+r reset to config: shown once something is set here; removes those values so config values and defaults apply again.

On V1, arrow keys aren't available in plugin dialogs: enter toggles the format and opens the custom interval prompt.

Changes take effect immediately. A value set in the TUI overrides config, and each setting shows where its current value comes from. TUI values are saved by OpenCode (plugin storage on V2, the TUI key-value store on V1) and survive restarts. On V2 they also sync across open TUIs. Config files are never modified.

Precedence: TUI setting, then cli.json (V2), then opencode.jsonc (V2) or tui.json (V1), then the default.

How it works

• V2: the server plugin resolves the active github-copilot credential and calls GET https://api.github.com/copilot_internal/user, then exposes the parsed result through an RPC (copilot-usage.get). The TUI plugin polls that RPC and renders the footer line and the /copilot-usage dialog.
• V1: the ./tui entry exports a V1 tui function next to the V2 setup. It reads the GitHub token from auth.json and calls the same endpoint itself.

[!NOTE] copilot_internal/user is an undocumented GitHub endpoint and may change without notice. Figures can lag slightly behind actual usage.

Development

npm install
npm run typecheck

To test a local checkout, uninstall the npm package first. Both register the same plugin ID.

OpenCode V2

A config path such as "plugins": ["D:/path/to/checkout"] is not loaded, and OpenCode doesn't follow symlinks or junctions in the plugins folder. Instead, create a small loader folder in the global plugins directory:

~/.config/opencode/plugins/copilot-usage-dev/
├── package.json
├── index.ts
└── tui.ts

package.json:

{
  "name": "copilot-usage-dev",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./index.ts",
    "./tui": "./tui.ts"
  }
}

index.ts:

export { default } from "/absolute/path/to/opencode-github-copilot-usage/src/index.ts"

tui.ts:

export { default } from "/absolute/path/to/opencode-github-copilot-usage/src/tui.tsx"

On Windows, use a drive path such as D:/development/opencode-github-copilot-usage/src/index.ts.

OpenCode doesn't watch the checkout. After editing, run opencode service restart and reopen the TUI. Restarting the service also stops running sessions.

Check that the plugin loaded:

opencode api get /api/plugin
opencode api post /api/rpc/copilot-usage/get --data '{"input":{"refresh":true}}'

In Git Bash on Windows, prefix these with MSYS_NO_PATHCONV=1 so the API paths aren't rewritten.

When you're done, delete the loader folder and reinstall the package:

rm -rf ~/.config/opencode/plugins/copilot-usage-dev
opencode plugin add opencode-github-copilot-usage

OpenCode V1

Point ~/.config/opencode/tui.json at the TUI file directly:

{
  "plugin": ["/absolute/path/to/opencode-github-copilot-usage/src/tui.tsx"]
}

Releasing

Releases follow semver. While on 0.x, fixes bump the patch version and new features or breaking changes bump the minor version. Breaking changes include renamed options, a changed plugin ID or RPC shape, and dropped OpenCode version support.

npm version patch          # or minor; runs typecheck, commits, and tags vX.Y.Z
git push --follow-tags

Pushing the tag runs .github/workflows/publish.yml. It checks the tag matches package.json, type-checks, stages the package on npm through trusted publishing, and creates a GitHub release. Approve the staged package on npmjs.com to make it public.

Pre-releases (npm version prerelease --preid beta) are staged under the beta dist-tag, so latest is unchanged.

License

MIT