Skip to content
claudemods

OpenRouter Balance: a Claude Code OpenRouter balance band above the prompt

Your OpenRouter credit above the Claude Code prompt: a balance gauge, today's spend and the model it mostly went to.

Permissions

  • Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
  • Runs commandsCan run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
  • NetworkCan make HTTP requests or talk to MCP servers ($.http.fetch / $.mcp.*).
  • Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
  • Adds commands/toolsRegisters new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
  • Stores dataKeeps data between sessions in the plugin's private store ($.store.*).
tested with
v2.1.310
last tested
requires
Claude Code ≥ 2.1.287
surfaces
above-prompt

Install inside Claude Code:

/plugin install openrouter-balance --marketplace hamzafer/claude-code-mods
All install options ↓

What does this mod do?

OpenRouter Balance is a community mod by Jakub Krysmalski (krysmalskipl), published in the claude-code-mods collection by Hamza Zafar. It puts your Claude Code OpenRouter balance in a band above the prompt, so you can see how much credit is left while you work with OpenRouter models.

The band shows a 10-block gauge, the amount left (green, yellow below $5, red below $2 with a "top up soon" note), what you spent today and, with a management key, the model the last 30 days' money mostly went to. On narrow terminals the gauge and model name are dropped. Type /openrouter-balance for the breakdown: balance, today, yesterday, the last 30 days, and spend per model with request and token counts.

With a regular API key the band falls back to that key's own numbers: today, this month and its limit if it has one. If the key limit runs out before the account balance, the band shows the key limit and says so.

Install

The install block above adds the author's marketplace and installs the plugin from it. Then give it a key. Open /config and paste it into the openrouter-balance field, set OPENROUTER_MANAGEMENT_KEY or OPENROUTER_API_KEY before starting Claude Code, or on macOS store it in Keychain. Until a key is found, the band reads "no key set, see /openrouter-balance".

$ install openrouter-balance

Requires Claude Code ≥ 2.1.287

Installs from the author's own marketplace: hamzafer/claude-code-mods

  1. 1.One line, inside Claude Code

    /plugin install openrouter-balance --marketplace hamzafer/claude-code-mods

    Paste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.

  2. 2.From your shell

    claude plugin marketplace add hamzafer/claude-code-mods
    claude plugin install openrouter-balance@claude-code-mods

    Then run /reload-plugins in any session that is already open.

  3. 3.Try it without installing

    git clone https://github.com/hamzafer/claude-code-mods
    claude --plugin-dir ./claude-code-mods/mods/openrouter-balance

    Loads the mod for one session only. Nothing is added to your settings.

How it works

The plugin is one function-hooks module, hooks/register.tsx. On session.start it registers /openrouter-balance, runs a first refresh in the background and starts a one-minute timer. A refresh calls three OpenRouter endpoints: /key, /credits and, for a management key only, /activity. The key is looked up like this, from register.tsx:

const k =
  configKey ||
  (await run(['printenv', 'OPENROUTER_MANAGEMENT_KEY'])) ||
  (await run(['printenv', 'OPENROUTER_API_KEY'])) ||
  (await run(['security', 'find-generic-password', '-s', KEYCHAIN_SERVICE, '-w']))
if (!k.startsWith('sk-or-')) throw new NoKey()

The band is drawn through the AbovePrompt render hook and passes along whatever other mods draw there. It also reads an optional band-order file written by the author's other mods, so several bands can be stacked in your preferred order.

Customize it

The only setting is the key field in /config. The thresholds (red below $2, yellow below $5), the five-minute refresh and the gauge width are constants in register.tsx; change them by forking the plugin and loading it with --plugin-dir. Band order is read from <config dir>/claude-code-mods/bands.json ({ "order": ["name", ...] }) once per session, so restart to apply a change.

Permissions & safety

We read every file the plugin can load: plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/bands.ts, types/index.d.ts and the test file. There are no binaries, no minified code, no install scripts and no dependencies. What we found:

  • Network: only https://openrouter.ai/api/v1 (/key, /credits, /activity) through $.http.fetch. Your key goes there as a Bearer header. Nothing else is sent, and there is no telemetry.
  • Processes: printenv OPENROUTER_MANAGEMENT_KEY, printenv OPENROUTER_API_KEY and security find-generic-password -s openrouter-key -w, each as an argv array with no shell. They exist only to find your key. The Keychain lookup reads only the item named openrouter-key, and macOS may ask you to allow access.
  • Files: reads bands.json under CLAUDE_CONFIG_DIR or ~/.claude/claude-code-mods/, and writes nothing there. The only thing it stores is the start-of-day usage mark in the plugin's own store. It does not touch settings.json, shell files or LaunchAgents, and starts no daemon.
  • Secrets: the key is held in memory only, not in state, the store or any message.
  • Model influence: it injects nothing into prompts and registers no gating hooks.
  • Requirements: an OpenRouter key. The mod is free, but it shows nothing useful without an account.
  • License: MIT, with a LICENSE file in the repository root.

claude plugin validate passed with one warning, a missing plugin icon, which does not affect loading. The author's 14 tests pass with claude plugin test on Claude Code 2.1.310; they use mocked network and process calls, so we did not call OpenRouter with a real key.

Reads files
Can read files and list directories on your machine ($.fs.read / list / stat / exists).
Runs commands
Can run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
Network
Can make HTTP requests or talk to MCP servers ($.http.fetch / $.mcp.*).
Changes the UI
Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
Adds commands/tools
Registers new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
Stores data
Keeps data between sessions in the plugin's private store ($.store.*).

Compatibility & troubleshooting

Tested on Claude Code 2.1.310. The mod needs function hooks, so use a recent build. If the band is missing or wrong:

  • "no key set": none of the four key sources has a value starting with sk-or-. Check /config, or restart Claude Code after exporting the variable.
  • "key rejected": OpenRouter answered 401 or 403. The key may be revoked, or it is not a valid OpenRouter key.
  • "can't reach OpenRouter yet" or "offline": the network failed. The band keeps the last numbers and retries after a minute.
  • Spend by model counts completed UTC days only, as OpenRouter reports it, so today's spend comes from the usage difference instead.

FAQ

Which OpenRouter key does the Claude Code OpenRouter balance band need?
A management key (openrouter.ai, Settings, Management keys) shows the real account balance and spend by model. A regular API key shows its own spend and limit, and the account balance too when OpenRouter lets that key read it. Without any key the band says "no key set".
Where does the mod look for my key?
In this order, the apiKey field in /config, the OPENROUTER_MANAGEMENT_KEY environment variable, OPENROUTER_API_KEY, and on macOS the Keychain item named openrouter-key. A key must start with sk-or-.
Does it send my key anywhere other than OpenRouter?
Not in the code we read. The only network host is openrouter.ai, and the key goes there as a Bearer token on the /key, /credits and /activity endpoints. There is no telemetry.
How often does it ask OpenRouter for the balance?
At session start, after each main-agent turn, and on a one-minute timer, but a refresh only goes out every 5 minutes, or one minute after a failure. The spend-by-model lookup is cached for an hour.
Why does it say "since 14:30" instead of "today"?
OpenRouter reports all-time usage, so the mod stores the usage it first saw each UTC day and subtracts it. If it first saw the day more than 15 minutes after midnight UTC, it shows "since" and the time it started counting.
Usage Meter running in Claude CodeFeatured

Usage Meter

Your plan's 5-hour and 7-day usage as small bars above the Claude Code prompt, with reset countdown and session cost.

  • above-prompt
  • toast
  • Changes the UI

tested with v2.1.291

Context Meter running in Claude CodeFeatured

Context Meter

Context-window fill, 5-hour and 7-day plan usage and session cost in the status line, plus a warning near the limit.

  • status
  • toast
  • Changes the UI

tested with v2.1.310

More in Context, quota, cost, Status line & prompt bar.