pi-claude-usage

Claude subscription usage for pi-claude-bridge sessions, shown in the Gentle Shell usage bar and /gentle:usage panel. Designed for Gentle Shell: with the shell loaded it registers claude-bridge on its official third-party usage-source event and feeds its native usage surfaces, just like built-in Codex sources. Without Gentle Shell it still provides a standalone status-bar segment, a /claude:usage subscriptions panel, and automatic refresh while claude-bridge is the active provider.

Why

Gentle Shell already meters the native anthropic provider by reading the anthropic-ratelimit-unified-* headers of every response. That provider bills per API call. To spend a Claude subscription (Pro, Max, Team) from Pi you go through pi-claude-bridge, which runs Claude Code via the Agent SDK. Claude Code makes the HTTP calls, Pi never sees those headers, and the claude-bridge provider shows no usage.

This package fills that gap. It registers claude-bridge on Gentle Shell's third-party usage-source contract (gentle-pi:usage-source/v1). When the shell refreshes usage, the source reads Claude Code's OAuth token and asks the same usage endpoint Claude Code's /usage view uses.

You get the 5-hour and weekly windows next to your other subscriptions. That includes the case where Claude only serves the subagent routes of a mixed profile, for example a zai main session with Claude reviewers.

What it shows

| Limit | Windows | When | | --- | --- | --- | | claude | 5h, week | Whichever windows the endpoint reports (a new account may report only 5h). | | opus, sonnet | week | Only when your plan reports per-model weekly caps. |

The plan label comes from Claude Code's subscriptionType (pro, max, team, ...).

Standalone (no Gentle Shell)

Without the shell the package works on its own whenever claude-bridge is the active provider:

• A status-bar segment (claude 5h ▰▰▰▱▱▱▱▱ 43% · week 12%) through pi's public ctx.ui.setStatus contract.
• /claude:usage opens the same framed ✿ Subscriptions panel the shell's /gentle:usage opens (r refreshes, esc closes). /claude:usage off hides the standalone segment; /claude:usage on restores it.
• Refreshes on session start and after agent runs, at most once every 5 minutes.

If gentle-shell acknowledges the usage-source registration (gentle-pi:usage-source-ack/v1), the standalone segment retires for the rest of the session, so the shell's own placement and visibility settings always win.

Install

Install it as a Pi package from npm:

pi install npm:@danielgap/pi-claude-usage

Then run /reload in Pi (or restart it). This adds the package to the packages array in ~/.pi/agent/settings.json:

"packages": [
  "/path/to/gentle-shell",
  "npm:pi-claude-bridge",
  "npm:@danielgap/pi-claude-usage"
]

You can also install straight from git, no npm involved:

pi install git:github.com/danielgap/pi-claude-usage

Requirements:

• pi-claude-bridge installed and its claude-bridge provider configured — the meter only fetches while it is the active provider.
• Claude Code logged in with a subscription (claude → /login).
• Gentle Shell is optional: with it you get the native usage bar and panel integration, without it the standalone segment and the /claude:usage panel.

Security model

• Read-only credentials. The token is read from $CLAUDE_CONFIG_DIR/.credentials.json (default ~/.claude/.credentials.json). It is never refreshed, written, logged, or rendered. If it has expired, the meter reports no usage until Claude Code refreshes it.
• Fixed origin. The token goes only to https://api.anthropic.com/api/oauth/usage. Redirects are refused, so it cannot be replayed to another host, and responses are not cached.
• No model call. The request only reads quota; it sends no prompt and runs no model.

Limitations

• Undocumented endpoint. Anthropic may change it at any time. Unknown shapes degrade to "no usage", never to an error.
• macOS. Claude Code stores its credentials in the Keychain there, so the file is missing and the meter stays empty.
• Refresh cadence. With Gentle Shell the shell owns it: on session start and when you press r in /gentle:usage (forced), and after agent runs at most once every 5 minutes. Standalone mode follows the same cadence itself.

This extension was built with Gentle AI.

Releasing

Releases publish automatically from version tags through .github/workflows/publish.yml:

1. Bump package.json to the next version, commit, and push to main.

2. Tag the release on the freshly fetched origin/main commit — the workflow verifies the tag is annotated, matches package.json's version, and points to a commit reachable from main:

   git fetch origin main --tags
   git tag -a vX.Y.Z "$(git rev-parse 'origin/main^{commit}')" -m "@danielgap/pi-claude-usage vX.Y.Z"
   git push origin refs/tags/vX.Y.Z

3. CI installs, tests, typechecks, packs, publishes to npm with provenance, creates the GitHub Release if it is missing, and verifies the registry. A brand-new package version can take a few minutes to appear in the registry after a successful publish, so the Verify npm step retries for up to 3 minutes before failing.

First-time setup: an NPM_TOKEN secret with publish rights is required under Settings → Secrets and variables → Actions. A run that failed for publication-only reasons can be retried without moving its tag (gh workflow run publish.yml -f tag=vX.Y.Z).

Development

pnpm install
npm test          # offline, fetch and file reads are injected
npm run typecheck

License

MIT