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 — live rate-limit utilization, rendered first in pi's footer, green → yellow → red as you burn through your windows.

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), 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 ≥ 0.77.

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

The line hides itself entirely when the active model isn't Anthropic-over-OAuth.

Data comes from Anthropic's OAuth usage endpoint — the same numbers behind Claude's /usage — refreshed at session start, on model change, after provider responses (throttled to 30s), and every 5 minutes while idle.

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

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 calls execute against the original tools. 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    # node --test, requires Node ≥ 23 (native TypeScript type stripping)

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.0.0 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 exactly one local change (tagged PCSC: inline, with an audit command in its header): a display-only renderCall on alias tools, so your terminal shows memory rather than mcp__hermes_memory__memory. Request payloads are byte-for-byte upstream behavior.

License

MIT — see LICENSE.