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-modsWhat 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.One line, inside Claude Code
/plugin install openrouter-balance --marketplace hamzafer/claude-code-modsPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add hamzafer/claude-code-mods claude plugin install openrouter-balance@claude-code-modsThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/hamzafer/claude-code-mods claude --plugin-dir ./claude-code-mods/mods/openrouter-balanceLoads 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_KEYandsecurity 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 namedopenrouter-key, and macOS may ask you to allow access. - Files: reads
bands.jsonunderCLAUDE_CONFIG_DIRor~/.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 touchsettings.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.
# Related mods
FeaturedUsage 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
FeaturedContext 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.