copilot-credit-guard

imageCI imageLicense: MIT imageVersion imageCopilot CLI plugin imagePRs welcome

Client-side monthly AI credit budget for the GitHub Copilot CLI, for people on a professional, Business or Enterprise seat who cannot set a per-user AI-credit budget for themselves. On those plans the native user-level budget is controlled by an organization or enterprise admin, so an individual member has no self-service way to cap their own spend. This plugin adds a personal, self-imposed cap that warns and blocks locally inside the Copilot CLI. Budgets are in credits (1 credit = $0.01).

This complements, and does not replace, GitHub's native budgets. Where you can set a native user-level AI-credit budget (which enforces a true hard stop across all surfaces), use that. This plugin is for the case where you can't, and want a local guard rail in the CLI. See Limits for what a client-side hook can and cannot do.

imagecredit-guard status

• Warns at 50% and 75% (once per level per month, and on every session start).
• Blocks tool calls (preToolUse deny) once the budget is reached.
• Resets on its own: usage comes from the account, which resets on the 1st (UTC).

Install

copilot plugin marketplace add Maximvdw/copilot-credit-guard
copilot plugin install copilot-credit-guard@maximvdw-tools

Or install directly from the repository: copilot plugin install Maximvdw/copilot-credit-guard. # optional: use the CLI outside Copilot ln -s "/scripts/credit-guard" ~/.local/bin/credit-guard

Needs gh logged in to the host (gh auth login; for a GHE.com tenant use --hostname <tenant>.ghe.com and set host), jq, awk. Installs are copies: after editing, run copilot plugin update copilot-credit-guard (or reinstall).

Screenshots

imageconfig

Use

CLI (anywhere):

credit-guard status [--short|--json]     # exit 0 ok, 1 warning, 2 over the block level
credit-guard config show
credit-guard config set budget 10000     # credits per month
credit-guard config set warn 50,75       # warning levels (percent)
credit-guard config set block 100
credit-guard override on|off             # stop/resume blocking
credit-guard config reset

Inside Copilot CLI: the credit-budget skill (/credit-budget, or just ask "what's my credit usage?") runs the same commands. Note that a skill call is a model call and costs a few credits. Use the plain credit-guard command for a free check.

Config

~/.config/copilot-credit-guard/config.json (created by config set; environment overrides it):

Limits

This is a client-side guard rail, not a billing control. Know what it can't do:

• It does not replace GitHub's native budgets. GitHub offers user-level AI-credit budgets that cap total consumption with a true hard stop across every Copilot surface. Where an admin lets you set your own, that is strictly stronger than this plugin. Use it.
• It cannot stop plain-text model charges. A hook can deny tool calls (preToolUse), but it cannot stop the model replying with plain text, which still costs credits. userPromptSubmitted exits 2 at the limit as a best effort; the CLI docs do not promise that this blocks the turn.
• It reads an undocumented endpoint. Usage comes from copilot_internal/user (quota_snapshots.premium_interactions.credits_used); GitHub may change or remove it. On any fetch error the hooks fail open and let the call through.
• Usage lags (local cache + server side), so the request that crosses the limit can overshoot before the next fetch sees it.

The warning, denial, override and fail-open paths are covered by functional tests (tests/run.sh, run in CI) that stub the usage endpoint; see Contributing.

Contributing

See CONTRIBUTING.md and SECURITY.md. Changes are listed in CHANGELOG.md.

Documentation

See docs/how-it-works.md for hooks, state files and exit codes.

License

MIT, see LICENSE. Author: Maxim Van de Wynckel maxim.vandewynckel@vlaanderen.be.