pi-claude-subscription-connector

Use your Claude Pro/Max subscription with pi — and see what's left of it in the footer.

🧠 5h 35% · wk 27% · fable 52%   🔌 MCP: 11 servers enabled   ✦ soul: global

Two things in one package:

1. Subscription billing — keeps Anthropic OAuth requests billed to your Claude plan instead of pay-per-token "extra usage".
2. 🧠 usage status line shows live Claude or OpenAI ChatGPT subscription utilization first in pi's footer, green → yellow → red as usage increases.

The problem it solves

Pi's built-in /login for Anthropic already authenticates against your Claude subscription. But Anthropic's API decides which bucket to bill by inspecting the request body, and a stock pi payload doesn't look like a first-party CLI request — extension tools carry flat names (web_search_exa, plannotator_submit_plan) and the system prompt talks about "pi itself".

Requests that don't match get billed to extra usage instead of your plan. If you have extra usage disabled or exhausted, you get a hard failure instead:

Error: 400 {"type":"error","error":{"type":"invalid_request_error",
"message":"You're out of extra usage. Add more at claude.ai/settings/usage..."}}

This package normalizes the payload so your subscription is used as intended: extension tools are advertised under MCP-style names (mcp__<server>__<tool>, a shape the endpoint accepts), including tools pi declares mid-conversation. Tool calls are mapped back before execution so the original extensions still run, and pi-specific wording in the system prompt is neutralized.

Install

pi install npm:pi-claude-subscription-connector

Then authenticate with your Claude account if you haven't already:

/login        # choose Anthropic → OAuth

Requirements: a Claude Pro or Max subscription, and pi ≥ 1.1.0 (the version this release is tested against).

Do not run this alongside @benvargas/pi-claude-code-use. Both rewrite the same payload and must not be stacked. The package detects this on startup and warns you which settings file to clean up.

The status line

Field	Meaning
5h 35%	Current 5-hour session window
wk 27%	Weekly limit, all models
fable 52%	Weekly limit for a specific model, labeled by name

Colors escalate automatically: green below 70%, yellow at 70–89%, red at 90%+.

Failures are never silent — every way the connector can break has a visible state:

Line	Color	Meaning
… ⚠ extra usage	red	A response reported billing to extra usage instead of your plan — the payload normalization may be broken (also notifies)
… ⚠ HTTP 400	red	Anthropic rejected a request outright (the "out of extra usage" failure signature; also notifies, clears on the next successful request)
🧠 login needed	yellow	OAuth token missing or rejected — run /login
… (stale)	usage color	Usage endpoint unreachable — still showing the last numbers that were read
🧠 usage n/a	yellow	Usage endpoint failing and no data has ever been read
🧠 …	dim	First fetch in flight

For OpenAI models signed in through ChatGPT, the same line shows the usage windows returned by OpenAI, for example:

🧠 5h 18% · wk 72%

Percentages show used capacity, not remaining capacity. Window durations come from OpenAI's response. Some plans return only a weekly window, shown as 🧠 wk 3%, rather than separate 5-hour and weekly limits. OpenAI request errors such as HTTP 429 appear as ⚠ HTTP 429 and clear on the next successful request. The extra-usage alarm remains specific to Anthropic.

The line supports Anthropic, OpenAI's legacy openai-codex provider, and the openai provider when authenticated with OAuth. It hides for API-key models and other providers. Usage numbers and error states are kept separate per provider.

Data comes from Anthropic's OAuth usage endpoint or OpenAI's ChatGPT usage endpoint (https://chatgpt.com/backend-api/wham/usage). It refreshes at session start, on model change, after provider responses (throttled to 30s per provider), and every 5 minutes while idle. OpenAI uses pi's existing sign-in credentials; no separate token or configuration is needed.

Configuration

Everything is optional. Config keys and environment variables are unchanged from the upstream package this vendors, so existing setups keep working.

Custom tool aliases — ~/.pi/agent/extensions/pi-claude-code-use.json (global) or <project>/.pi/extensions/pi-claude-code-use.json (project):

{
  "toolAliases": [["my_tool", "mcp__myserver__my_tool"]]
}

Aliases are derived automatically; this is only for overrides.

Environment variables

Variable	Effect
PI_CLAUDE_CODE_USE_DISABLE_TOOL_FILTER=1	Pass all tools through unchanged
PI_CLAUDE_CODE_USE_DISABLE_AUTO_ALIAS=1	Only use aliases you configured
PI_CLAUDE_CODE_USE_DEBUG_LOG=<path>	Log payloads before/after transform
PI_CLAUDE_CODE_USE_DISABLE_PROSE_UNALIAS=1	Show assistant text exactly as the model wrote it, alias names included

Tool names in your terminal

Extension tools are advertised to Anthropic under MCP-style aliases, but that renaming is invisible locally. Tool calls render with their original names and arguments, assistant text that mentions an alias shows the original name, and calls execute against the original tools, including calls from codemode scripts. The alias only exists on the wire.

(The one place aliases remain visible is the /tools picker, where each alias is listed as a selectable tool labeled MCP <name>.)

For extension authors

If you write pi extensions and want your tools to work cleanly here, register them under an MCP-style name (mcp__<server>__<tool>) directly. Those pass through untouched, with no aliasing round-trip.

Development

npm test    # links your installed pi into node_modules, then runs node --test (Node ≥ 23)

Extensions are plain TypeScript with no build step — pi loads them through jiti.

Credits

extensions/subscription-guard.ts is vendored from @benvargas/pi-claude-code-use v2.2.1 by Ben Vargas (MIT). That package worked out which payload changes matter; this one packages it together with the usage status line. If you only need the billing fix, use his package directly.

The vendored file carries three local changes, each tagged PCSC: inline and listed in its header along with a command to diff it against upstream:

• Tools pi defines mid-conversation (pi ≥ 1.0.1 sends them inline in tool_addition blocks) get the same MCP-style names as the request-level tool list. Upstream only renames tools referenced by name there, so this is where request payloads differ from upstream's.
• Alias tools forward calls to the original tool, so codemode scripts can call them.
• Alias tool calls render with the original name and arguments, so your terminal shows memory rather than mcp__hermes_memory__memory.

License

MIT — see LICENSE.