pi-claude-bridge: running Claude Code as a model provider inside pi

A provider, not a chat window, and that distinction drives the design

pi-claude-bridge is an extension for pi that integrates Claude Code through the Agent SDK, and the repository description frames it as a Claude Code inference provider for pi that allows the use of Pro and Max subscriptions from pi.dev. It was originally based on claude-agent-sdk-pi by Prateek Sunal.

The README names two features, and the first is the provider. With it, you select any Claude model in pi-ai's catalog and use it inside pi, with all tool calls flowing through pi's TUI. The second is an AskClaude tool for delegating a task to Claude Code while you are on another provider.

The phrasing about tool calls is where the real difference lies. This is not a wrapper that forwards your prompt to a model and prints the reply. The bridge takes pi's structured request parts, translates them for Claude Code, and lets Claude Code's own tool execution run inside the pi session, with the results coming back into the pi interface.

The README describes the set of parts that are forwarded: project context files, skills, the custom prompt, appended instructions, and the custom prompt sections under `systemPromptOptions.sections`. Everything else in the request is dropped. That selective forwarding is the mechanism to understand, because it explains both what works and what does not.

One commercial caveat is stated up front. The README notes that Anthropic announced and then unannounced a change to how tools using the Agent SDK would be billed, and that it currently uses your regular subscription quota just like Claude Code. So the model access is paid for through the subscription rather than through API credits, at least as the documentation describes the current state.

Model selection comes from pi-ai's catalog, not from a hardcoded list

You pick a model with the `/model` command, and the identifiers are namespaced under `claude-bridge`, for example `claude-bridge/claude-fable-5-1`, `claude-bridge/claude-opus-5` or `claude-bridge/claude-haiku-4-5`.

What makes this pleasant is where the list comes from. The README states that the model list comes from pi-ai's Anthropic catalog automatically, so when pi-ai adds a new Claude model it appears in `/model` after you update the package, with no bridge update required. Dated snapshot ids, with an example given as `claude-opus-4-5-20251101`, are not shown.

That last detail is a real constraint for anyone who pins model versions deliberately. If your workflow depends on a specific snapshot for reproducibility, the picker will not offer it.

Long context is handled by model tier and by plan, and the mapping is specific. Fable 5 and 5.1, Opus 5.5, 5, 4.8 and 4.7, and Sonnet 5.5 and 5 get 1M context. Opus 4.6 gets 1M only on a Max plan or with Extra Usage, and Sonnet 4.6 only with Extra Usage. Reaching those requires setting `provider.plan` and `provider.longContextExtraUsage`.

The escape hatch for the mismatches is `provider.forceTwoHundredK`, an array of model ids to pin to 200K context, given as bare ids without the `[1m]` suffix. The README explains why it exists: pi-ai may declare a model at 1M while Claude Code will not serve it on your plan.

Bridging pi's tools to Claude Code changes the timeout and the skill flow

Behind the scenes, the README is specific about three seams where the two systems meet.

Bash commands get Claude Code's 120-second default timeout, because pi's bash has none. That is a meaningful behavioral difference for long-running commands, and it is not configurable in the documented configuration.

Skills are forwarded into Claude Code's system prompt, and steering mid-turn reaches Claude at the next tool boundary. That second point has a practical consequence: a message you type while a turn is running does not interrupt it. It is queued and delivered when the model next reaches a point where it can accept input.

The AskClaude tool is the other half of the feature set, and the README is blunt about its status. It is described as an opt-in legacy tool that may be removed in a future release, and to use it you have to set `askClaude.enabled` to `true`, because if that setting is unset a startup notice points this out once. The README also says the functionality can be recreated with one of the many Pi subagent extensions, which is a reasonable path if you were planning to lean on it.

The tool itself is configurable in ways that matter for a delegation tool. `askClaude.defaultMode` is `"read"` by default, with `"none"` and `"full"` as alternatives, and `askClaude.allowFullMode` can be set to false to lock full mode out entirely. `askClaude.defaultIsolated` starts each call in a fresh session, and the name, TUI label and tool description can all be overridden.

The config file merges project over global, and MCP access is blocked by default

Configuration lives in `~/.pi/agent/claude-bridge.json` globally, or in the project Pi config directory, usually `.pi/claude-bridge.json`, with the project file merged over the global one. The documented example shows both shapes at once:

{
  "askClaude": {
    "enabled": true,
    "allowFullMode": true,
    "defaultIsolated": false,
    "description": "Custom tool description override"
  },
  "provider": {
    "plan": "max",
    "longContextExtraUsage": false,
    "strictMcpConfig": true,
    "pathToClaudeCodeExecutable": "/home/you/.nix-profile/bin/claude"
  }
}

The `provider.plan` setting defaults to `"pro"` and should be set to `"max"` if you have a Max, Team Premium or Enterprise plan, which the README says enables Opus with 1M context.

The setting with the most security weight is `strictMcpConfig`, which defaults to true and blocks MCP servers from `~/.claude.json` and `.mcp.json`. Cloud MCP, meaning Gmail and Drive through claude.ai OAuth, is always blocked regardless of the setting. This is a deliberate containment decision, and it changes what a user can do: an MCP server you configured for Claude Code will not be visible to the bridge unless you turn the guard off, and the cloud connectors cannot be turned on at all.

`pathToClaudeCodeExecutable` covers a specific failure mode. The SDK ships bundled musl and glibc binaries, and on some systems those cannot run, so you can point at your own `claude` binary. The Nix example in the README is exactly this case.

Two other provider options round out the list. `autoMemoryEnabled` turns on Claude Code's auto-memory system and defaults to false, and `forceTwoHundredK` pins specific models as described above.

modelOverrides in models.json does not reach an extension-registered provider

This is the sharpest limitation in the README, and it is a footnote rather than a feature description.

Pi's `modelOverrides` in `~/.pi/agent/models.json` do not currently apply to extension-registered providers like claude-bridge. To override `contextWindow` or any other field, you have to edit `src/models.ts` directly, inside the installed package. The README then points you at the supported route: to pin a model to 200K, use `provider.forceTwoHundredK` instead.

In practice this means the JSON override mechanism that works for pi's built-in providers does not work here, and the sanctioned workaround is a single purpose-built option. A user who wants to adjust a context window for a model the catalog has declared as 1M but that Claude Code will not serve on their plan has exactly one documented lever, and any other adjustment requires patching a file in `node_modules` or an equivalent install location.

The package manifest explains the shape of the dependency. The runtime dependencies are `@anthropic-ai/claude-agent-sdk` at `^0.3.293`, `@modelcontextprotocol/sdk` at `^1.29.0`, `cc-session-io` at `^0.4.0` and `change-case` at `^5.4.4`. The pi side is a peer dependency rather than a direct dependency, with `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` all pinned at `>=0.86.1` and `typebox` at `*`. Node 20 or newer is required by the `engines` field.

The `cc-session-io` dependency and the session-synchronization behavior in the debug output point at the part of the system that carries the most risk of subtle bugs, namely resuming a Claude Code session from pi. That is where the failure mode documented in the tests comes in.

Resuming a session needs a writable ~/.claude, and the failure message is misleading

The README describes a specific failure that is easy to misread. Integration tests spawn real `pi` and Claude Code subprocesses and need write access to `~/.claude`, and a sandbox that blocks it makes `--resume` fail with "No conversation found with session ID".

The error message points at a missing conversation, which suggests a lost or unknown session, when the actual cause is a filesystem permission problem in the home directory. Anyone hitting this in a container, a restricted CI runner, or a locked-down workstation will spend time on session ids before finding the real cause.

The test setup reflects that. `npm run test:unit` runs the offline tests, while `npm test` adds integration tests that hit APIs, and it expects a `CLAUDE_BRIDGE_TESTING_ALT_MODEL` value in `.env.test` for the alt-provider smoke test. The full test script chains several shell scripts, `tests/int-smoke.sh`, `tests/int-multi-turn.sh` and `tests/int-cache.sh`, then the integration TypeScript tests, and finally a deadlock log check.

For debugging, the bridge writes two kinds of log. `CLAUDE_BRIDGE_DEBUG=1` turns on debug output, with a bridge log at `claude-bridge.log` in pi's agent directory, which is `PI_CODING_AGENT_DIR` and defaults to `~/.pi/agent`, holding provider calls, session sync decisions, tool results and Claude Code's stderr. The location can be overridden with `CLAUDE_BRIDGE_DEBUG_PATH`. Alongside it, per-query Claude Code CLI logs land in `cc-cli-logs/<timestamp>-<tag>-<seq>.log` in the same directory, where the tag is `provider` or `askclaude`, showing session loading, API requests and tool calls from the subprocess's own point of view.

The README also gives the recipe for bug reports about resume failures: attach the `syncResult:` lines from the bridge log plus the matching file from `cc-cli-logs/`. That pairing is the most useful diagnostic detail in the document, because the bridge log says what it decided and the CLI log says what actually happened.

A pi subagent extension does the delegation without the subscription coupling

The alternative to this extension is not another bridge. It is using pi's own subagent extensions for the delegation part, which the README itself points to when it describes AskClaude as a legacy tool whose functionality can be recreated with one of the many Pi subagent extensions.

The difference in approach is worth being concrete about. A subagent extension runs a subagent inside pi's own provider setup, so the delegated work goes through whatever model pi is already configured to use, and the results come back as pi-native messages. pi-claude-bridge instead spawns Claude Code, a separate agent runtime with its own tools, its own filesystem behavior and its own session model, and injects it into the pi request.

That buys specific things. Claude Code's tool set, its skills handling and its 120-second bash timeout come along for the ride, and the model catalog is Anthropic's, reached through pi-ai. It costs specific things too. You inherit Claude Code's session semantics, which is exactly where the `~/.claude` write permission and the `syncResult:` log lines come from, and the bridge maintains its own bridge log on top of pi's.

The subscription angle is the real differentiator. If you have a Claude Pro or Max plan and want to use it inside pi, this bridge is the route, because the Agent SDK path draws on the subscription quota rather than an API key, as the README describes. If you are on API billing and want a second opinion inside pi, a subagent extension on a cheap model is the simpler arrangement, and it avoids the extra process, the session resumption and the two log formats.

For the provider role specifically, there is no comparable alternative inside pi, because no other extension makes Claude Code the model driving the session. The repository is MIT licensed, the package is published to npm as `pi-claude-bridge` at version 0.9.3, the repository is not archived, and the last push was on 2026-10-22.

Editorial conclusion

Use pi-claude-bridge when you already pay for a Claude Pro or Max plan and want Claude Code's tool use inside pi's terminal interface without a second API bill. Do not adopt it if you need a plain API key, if your work depends on AskClaude, which the README marks as a deprecated legacy tool, or if you need model overrides through models.json, since extension-registered providers ignore that file. Verify first that your pi version is 0.86.1 or newer, and set `provider.strictMcpConfig` deliberately, because the default blocks MCP servers from ~/.claude.json and .mcp.json, and cloud MCP through claude.ai OAuth is blocked either way.

Frequently asked questions

Official sources

1. elidickinson/pi-claude-bridge on GitHub
2. Issues
3. License: MIT
4. README