pi-anthropic-auth

A Pi extension that improves compatibility with Anthropic Claude Pro/Max OAuth (i.e., your Claude subscription) while preserving Pi's normal Anthropic behavior.

What It Does

Pi works great with Anthropic API keys out of the box. This extension fills in the gaps for users who want to use their Claude Pro or Max subscription via OAuth instead.

It keeps everything you'd expect — the built-in anthropic provider, the full model list, API-key behavior, and the native /login anthropic flow — and layers on the compatibility fixes needed to make OAuth subscriptions work reliably.

Requests to non-Anthropic providers and plain API-key Anthropic requests pass through completely untouched — the extension only activates when it detects an Anthropic OAuth access token (sk-ant-oat).

Shaping runs in a thin transport wrapper around Pi's own Anthropic transport, so it applies to interactive turns and to compaction — not just the main turn. Background agents that run their own agent loop are a known exception on Pi 0.80.8 and later. See docs/architecture.md for how this works, and for the workaround if you write such an extension.

Pi's own extra-usage warning still appears on every Anthropic OAuth session and is not suppressed by this extension — see Pi warns about extra usage on every OAuth session.

Install

pi install npm:@gotgenes/pi-anthropic-auth

To try it without permanently installing:

pi -e npm:@gotgenes/pi-anthropic-auth

Usage

1. Run /login anthropic as usual — Pi's native Anthropic login flow is preserved.
2. Select a Claude Pro/Max model and start chatting. The extension handles compatibility transparently.
3. API-key behavior is unaffected; the extension's changes apply only to OAuth sessions.

Troubleshooting

Verify the extension is loaded

Run /anthropic-auth:status in Pi to print a diagnostics report:

pi-anthropic-auth diagnostics
  version: 0.6.5
  module:  /root/.pi/agent/.../src/index.ts
  built-in Anthropic transport: resolved

The module line shows which copy of the extension loaded. If the command is not found, the extension is not loaded at all.

Pi warns about extra usage on every OAuth session

Pi prints this warning once per interactive session whenever an Anthropic model is selected and your stored Anthropic credentials are OAuth:

Anthropic subscription auth is active. Third-party harness usage draws from extra usage and is billed per token, not your Claude plan limits. Manage extra usage at https://claude.ai/settings/usage. Disable this warning in /settings.

Installing this extension does not silence it, and that is not a sign the extension is broken. Pi's check looks only at which provider the selected model belongs to and whether the stored credential is an OAuth token. It has no way to see that a provider registration is in place, so no extension can suppress it.

The warning is also not entirely wrong. Interactive turns and compaction go through this extension's request shaping; requests from background agents that run their own agent loop do not, and for those the warning describes exactly what happens. See docs/architecture.md for the full call-path table.

This is a startup notice, not a failure. A request that actually fails with an HTTP 400 saying You're out of extra usage. is a different problem — start with Verify the extension is loaded.

Pi owns the switch for this warning, so the extension leaves it alone. Turn it off yourself with /settings → Warnings → "Anthropic extra usage", or set it in ~/.pi/agent/settings.json:

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

Because the warning concerns real billing on paths this extension does not cover, that call is yours to make; the extension will never write the setting for you.

ANTHROPIC_API_KEY is ignored when OAuth credentials exist

Pi's auth resolver gives stored credentials priority over environment variables. If you have previously run /login anthropic and credentials are stored in ~/.pi/agent/auth.json, Pi uses the stored OAuth token on every request — even when ANTHROPIC_API_KEY is also set.

To use the API key instead, run /logout anthropic inside Pi to remove the stored credentials, or delete auth.json before starting the session.

A new model is rejected as claude_code_version_too_old

Anthropic gates newly released models on a minimum Claude Code version:

400 invalid_request_error: Claude Code 2.1.206 does not support this model;
version 2.1.251 or newer is required.
details.error_code: claude_code_version_too_old

This package reports a bundled Claude Code version in the OAuth billing header. When Anthropic raises the floor faster than a release ships, override the pin:

export PI_ANTHROPIC_AUTH_CLAUDE_CODE_VERSION=2.1.260

The value must be a bare X.Y.Z version; anything else fails fast with an explicit error. Check the current release with npm view @anthropic-ai/claude-code version.

Do not derive the value from a local claude --version. Claude Code's stable release channel lags latest, so an installed copy is often below the floor a new model requires.

If the version in the error message is not the one this package reports, the request is being rejected on Pi's own user-agent: claude-cli/<version>, which this extension does not control. That pin lives in Pi's pi-ai package and needs a Pi upgrade.

/compact fails with a Terms of Service message

Compaction failed: Turn prefix summarization failed: This request was blocked as it seems to
violate Anthropic's Terms of Service restrictions on reverse engineering or duplicating model
outputs.

This is Anthropic's reasoning_extraction classifier, and this extension does not fix it.

Measured cause: pi's turn-prefix summarization prompt asserts "This is the PREFIX of a turn that was too large to keep" while sending a transcript of only a few hundred characters, mostly model output. On claude-fable-5-1 that combination is refused; it fades out above roughly 3,000 characters of transcript and does not occur on claude-fable-5, nor with pi's full compaction prompt.

The fix belongs upstream — tracked at earendil-works/pi#9652 and #65. As a workaround, compact on a different model, or avoid the turn-prefix path by compacting before a single turn grows large enough to be split.

Docker: extension missing after volume mount

If you install the extension at image build time with RUN pi install npm:@gotgenes/pi-anthropic-auth and then mount a persistent volume over ~/.pi/agent at runtime, Docker may mask the build-time install. Docker seeds a named volume with the image directory only on its first creation. If the volume already exists from a previous image, the extension directory inside it may be empty or out of date.

To fix this, either:

• Remove the volume and let Docker re-seed it: docker volume rm <volume-name>.
• Or install the extension at container startup rather than at image build time, after the volume is mounted.

Development

Requirements

• pnpm
• a local pi installation
• Anthropic OAuth credentials configured through Pi

Commands

pnpm install      # install dependencies
pnpm run check    # typecheck
pnpm test         # run tests
pnpm run build    # compile

Load a Local Build

pi -e /absolute/path/to/pi-anthropic-auth/dist/index.js

Debug Logging

Set PI_ANTHROPIC_AUTH_DEBUG to enable structured debug logs from the OAuth shaping layer.

Modes:

• PI_ANTHROPIC_AUTH_DEBUG=all — log all Anthropic OAuth shaping events
• PI_ANTHROPIC_AUTH_DEBUG=tool-use — log only requests that include tool_use

Example:

PI_ANTHROPIC_AUTH_DEBUG=tool-use \
pi \
  --model anthropic/claude-haiku-4-5 \
  --no-session \
  --tools read,grep,find,ls \
  -e /absolute/path/to/pi-anthropic-auth/src/index.ts \
  -p "How many lines are in @AGENTS.md ?"

Similar Projects

• opencode-anthropic-auth — Anthropic OAuth compatibility work for OpenCode.
• pi-anthropic-oauth — a Pi extension that takes a fuller provider-override approach.

For notes on how this project compares to similar work, see docs/comparison-to-similar-projects.md.

Acknowledgments

This project was inspired by opencode-anthropic-auth, which solved the same Anthropic OAuth compatibility problem for OpenCode.

License

MIT