pi-claude-code-provider

This project is mothballed after the release of v0.6.0. Pi and Claude Code are both extremely fast-moving projects that publish breaking changes regularly, and this was a hobby project rather than a professional venture, so I have other plans for my time and my tokens. I encourage people to look for other providers, such as pi-claude-bridge, which is built on the Agent SDK. Please do not report further issues or submit pull requests. If Pi and Claude Code stabilize in future months, I may revisit this project. I thank my users for their kind words and wish everyone good luck with their own efforts.

A Pi package that creates a provider for Claude family models from a subscription-authenticated Claude Code installation by launching Anthropic's installed claude executable in documented non-interactive print mode. Pi remains fully in charge of the session: branching, compaction, and history behave like any other Pi provider, and every tool runs visibly in Pi — the Claude process can propose tool calls but never execute anything on its own. The goal is simple: the convenience of your Claude subscription in Pi, with the fewest possible surprises.

This package never imitates private OAuth traffic, does not use the Agent SDK, and does not modify Claude's internal session files. It never reads Claude credentials or uses an Anthropic API key.

This project was developed using frontier AI models under human guidance. Almost all of the docs and code were written by machines except for this introductory material. The project may be over-engineered in some respects; that's fine. If you enjoy this package, please star it on github.

Requirements

• Pi 0.86.1 or newer, installed from npm or a standalone build
• Claude Code 2.1.281 or newer
• Claude Code logged in to an eligible Pro, Max, Team, or Enterprise claude.ai subscription
• Node.js 22.19 or newer only when Pi itself is installed from npm; the standalone build needs no separate Node installation

These are minimum versions; see the compatibility baseline for tested versions and platforms. The doctor warns about older versions and unverified platforms.

The provider requires first-party subscription authentication. API keys and routing through Bedrock, Vertex, or Foundry are unsupported. If claude is not on PATH, set PI_CLAUDE_CODE_PROVIDER_PATH to its executable path.

Install

pi install npm:pi-claude-code-provider

To install directly from GitHub's default branch:

pi install git:github.com/chem/pi-claude-code-provider

Add -l for a project-local installation. Pi loads project packages only after the project is trusted; use pi config to enable or disable the extension.

For a local checkout, use pi install /absolute/path/to/pi-claude-code-provider. The startup [Extensions] list shows chem/pi-claude-code-provider for Git and pi-claude-code-provider for npm or a local checkout with that directory name. A renamed checkout shows its directory name. These labels apply to npm and standalone Pi alike.

Use

Open /model and choose sonnet, fable, opus, or haiku under pi-claude-code-provider.

To select one directly:

/model pi-claude-code-provider/sonnet

From the command line, use pi --model pi-claude-code-provider/sonnet.

Sonnet, Fable, and Opus support Pi thinking levels from low through max. Haiku uses Claude Code's default thinking, even when Pi shows thinking as off. Sonnet, Fable, and Opus have a 1M context window on every plan, including Pro; Haiku has 200K.

Fable availability and billing vary by subscription tier; see Anthropic's Fable plan policy.

To see which model served a response, inspect responseModel in Pi's JSON output.

Pi's active tools are advertised through MCP. If the model omits the MCP prefix on exactly bash, read, edit, or write, the provider accepts that name only when the same lowercase Pi tool is active. Bare capitalized names such as Bash and bare names of other tools remain errors. Arguments must still follow Pi's advertised schema; the provider does not translate Claude Code's built-in argument fields or timeout units.

After installation or an upstream update, run:

/pi-claude-code-provider-doctor

The doctor checks versions, model aliases, and the tool bridge without consuming subscription quota. It names the provider version Pi actually loaded and its install directory, which exposes an older project-local or duplicate installation. It also reports recent prompt-cache reuse and context-window mismatches. Its last-request metrics describe the request whose process cleanup and lifecycle finished most recently; overlapping requests can finish out of start order, and a terminal response can appear before its metrics finalize.

Run /pi-claude-code-provider-doctor report for a content-free diagnostic report. Inspect it before sharing it.

The pi_claude_code_provider_web_search tool uses Claude's WebSearch and WebFetch. It always uses Sonnet at medium effort, regardless of the selected model, and has a three-minute limit. Pi offers it to every model, including other providers' models, so each call consumes Claude subscription capacity. Its prompt guidance defers to any other web-search tool you have. To remove it entirely, set PI_CLAUDE_CODE_PROVIDER_WEB_SEARCH=off; for a single launch, pi --exclude-tools pi_claude_code_provider_web_search also works. If it is unexpectedly unavailable, run the doctor, which reports its state, then check that variable, Pi's tool filters, and whether another extension owns the name.

Subscription usage

Provider and web-search requests consume Claude subscription capacity; canceling a running request may still consume it. Optional usage credits may incur additional spend after plan limits. The package reports token counts when available, but shows zero monetary cost because it cannot determine subscription billing.

This project uses Anthropic's documented claude --print interface. Anthropic explains subscription limits for third-party usage and usage credits.

Pi shows Claude's rate-limit warnings and reset times when available.

Compatibility limitation

Claude Code's public headless protocol cannot accept arbitrary past assistant messages or tool results. The provider therefore sends Pi's current history on every request. Pi still owns branching, compaction, and tool execution, but this transport uses more context than Anthropic's Messages API. See DESIGN.md for caching and performance details.

Images remain available throughout the current Pi context. Each request allows up to 20 images, subject to size limits; DESIGN.md describes their transport.

Configuration

Metrics exclude prompts, messages, queries, output, credentials, stderr, and temporary paths. On POSIX, the log is mode 0600; Windows uses the selected location's ACL.

Claude receives an allowlisted environment, including CLAUDE_CONFIG_DIR for a relocated configuration and NODE_EXTRA_CA_CERTS for a proxy's CA bundle.

Security and troubleshooting

Pi packages run with your permissions; review the source before installation. Claude runs in Pi's session working directory and can read some project files at startup. Its proposed file and shell actions run as visible Pi tools. The provider suppresses user and project Claude customizations, but administrator-managed settings, hooks, and MCP policy can still run. See DESIGN.md for startup behavior and SECURITY.md for vulnerability reporting.

Tool-bearing side requests need a registered Pi session or a working-directory declaration in the system prompt. That declaration is caller-controlled; see DESIGN.md for routing details.

The provider rejects detected tool arguments aimed at its private request and image directories, including equivalent path spellings resolved against the request's working directory. It also recognizes the temporary directory's alias spellings, such as macOS's /var/folders for /private/var/folders. This guard is a heuristic: it does not follow other symlinks or interpret arbitrary shell expressions. Pi tools run with your permissions.

Troubleshooting

• Provider missing or unavailable: run /pi-claude-code-provider-doctor, correct the problem it reports, then run /reload.
• Windows reports Claude Code missing although claude works in your shell: that claude is probably a .cmd or .bat shim, such as an npm install creates, which cannot run without a shell. Install the native Claude Code (claude.exe), or set PI_CLAUDE_CODE_PROVIDER_PATH to Claude Code's JavaScript entry point.
• Requests fail right after Claude Code updated: run the doctor. If it reports your Claude Code version as unverified, install the tested version it names with claude install <version>. To avoid a repeat, set "autoUpdatesChannel": "stable" in Claude Code's settings, which waits about a week and skips releases with major regressions, or set DISABLE_AUTOUPDATER to "1" in their env. See Claude Code's setup guide.
• Authentication or subscription failure: run claude auth status and sign in with an eligible subscription. For rate-limit or billing errors, check your subscription limits and usage-credit settings. Logins through CLAUDE_CODE_OAUTH_TOKEN are unsupported.
• Tools fail or requests report mcp_startup: run the doctor to check the tool bridge handshake.
• "The model refused to complete the request": Fable, Opus 5.5, and Opus 5 run safety classifiers, most often triggered by cybersecurity and biology content, including context such as project files. Claude Code can re-run a flagged request on another model, but the provider turns that switch off because it cannot publish a response rewritten mid-stream, so the request ends with this error and Pi does not retry it. See Anthropic's automatic model fallback.
• A request keeps failing: run /pi-claude-code-provider-doctor report and inspect the report before sharing it.

Development and license

See DEVELOPING.md, CONTRIBUTING.md, and DESIGN.md. Licensed under MIT.