pi-claude-bridge

Pi extension that integrates Claude Code via the Agent SDK. Based initially on claude-agent-sdk-pi by Prateek Sunal. This fork adds streaming, MCP tool bridging, custom pi tool bridging, session resume/persistence, context sync, thinking support, skills forwarding, and many correctness fixes.

1. Provider — Use Opus/Sonnet/Haiku as models in pi, with all tool calls flowing through pi's TUI
2. AskClaude tool — Delegate tasks or questions to Claude Code when using another provider

FYI: Anthropic announced and then unannounced a change to how you would be billed for tools that use the Agent SDK like this one. It currently uses your regular subscription quota just like Claude Code.

Install

pi install npm:pi-claude-bridge

Requires pi 0.85.0 or newer (pi-ai, pi-coding-agent, pi-tui); pi 0.86 needs bridge 0.8.0 or newer. With an older pi-ai the model picker comes up empty, and the bridge logs which dependency to update.

Provider

Use /model to select any Claude model in pi-ai's catalog, e.g. claude-bridge/claude-fable-5-1, claude-bridge/claude-opus-5, or claude-bridge/claude-haiku-4-5.

Behind the scenes, pi's tools are bridged to Claude Code but it should all work like normal in pi. Bash commands get a 120-second default timeout (matching Claude Code's default) since pi's bash has no timeout by default. Skills in pi are copied over to Claude Code's system prompt so should work as they would with any other pi provider. Steering works mid-turn: a message sent while Claude is running a tool reaches it at that tool boundary, not after the whole turn finishes.

The model list comes from pi-ai's Anthropic catalog automatically — when pi-ai adds a new Claude model, it appears in /model after updating the package, no bridge update needed. Dated snapshot ids (e.g. claude-opus-4-5-20251101) are not shown. Selection by shortcut or partial id always prefers an exact match first, then the newest version of the matching family.

1M Context: 1M is enabled per a measured list — models verified to serve 1M through the SDK on every plan (Fable 5/5.1, Opus 5/4.8/4.7, Sonnet 5). A new model appearing from pi-ai starts at 200K context until it's measured and added to that list, so no model can 400/429 its way through every turn. Opus 4.6 only gets 1M if you're on a Max plan or pay for Extra Usage. Sonnet 4.6 only gets 1M if you pay for Extra Usage. You will need to set provider.plan and/or provider.longContextExtraUsage for 1M context in Opus 4.6/Sonnet 4.6 as described in Configuration.

AskClaude Tool

Opt-in: set askClaude.enabled to true (see Configuration). Available when using any non-claude-bridge provider. Pi's LLM can delegate tasks to Claude Code and wait for it to answer a question or perform a task. Examples of how to use:

• "Ask Claude to plan a fix"
• "If you get stuck, ask claude for help"
• "Ask claude to review the plan in @foo.md, implement it, then ask an isolated=true claude to review the implementation"
• "Ask claude to poke holes in this theory"
• "Find all the places in the codebase that handle auth"

Delegated calls are isolated from your ~/.claude estate: children don't read global CLAUDE.md files or Claude Code's skill listing, and always get Claude Code's own system prompt preset.

You could also create skills or add something to AGENTS.md to e.g. "Always call Ask Claude to review complicated feature implementations before considering the task complete."

Parameters

• prompt — the question or task for Claude Code
• mode — read (default, read files and search/fetch on web), none, or full (read+write+bash, disable this mode with allowFullMode: false in config)
• model — opus (default), sonnet, haiku, or a full model ID
• thinking — effort level: off, minimal, low, medium, high, xhigh
• isolated — when true, Claude gets a clean session with no conversation history (default: false)

Configuration

Config: ~/.pi/agent/claude-bridge.json (global) or the project Pi config directory, usually .pi/claude-bridge.json (project; merged over global).

{
  "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"
  }
}

askClaude:

• enabled — register the AskClaude tool (default false). If it's unset, the startup notice below points this out once.
• name — override the tool's pi-side name (default "AskClaude")
• label — override the TUI label (default "Ask Claude Code")
• description — override the tool description. Default when allowFullMode: true: "Delegate to Claude Code for a second opinion or analysis (code review, architecture questions, debugging theories), or to autonomously handle a task. Defaults to read-only mode — use full mode when the user wants to delegate a task that requires changes. Prefer to handle straightforward tasks yourself."
• defaultMode — "read" (default), "none", or "full"
• defaultIsolated — start each call in a fresh session (default false)
• allowFullMode — allow mode: "full"; set false to lock it out
• appendSkills — forward pi's skills block into the system prompt (default true)

provider:

• plan (default "pro") — set to "max" if you have a Max (or Team Premium/Enterprise) Anthropic plan. This enables Opus with 1M context.
• longContextExtraUsage — set to true to enable 1M context models even if they cost money through Extra Usage on your plan. It enables Sonnet 4.6 with 1M on every plan and Opus 4.6 with 1M on Pro. Not needed for Opus 4.7 or 4.8.
• forceTwoHundredK — array of model ids to pin to 200K context (bare id, no [1m] suffix). Use if pi-ai declares a model at 1M but Claude Code won't serve it on your plan.
• strictMcpConfig — block MCP servers from ~/.claude.json / .mcp.json (default true). Cloud MCP (Gmail/Drive via claude.ai OAuth) is always blocked.
• autoMemoryEnabled — enable Claude Code's auto-memory system (default false)
• pathToClaudeCodeExecutable — path to the claude binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run. For example, with Nix you can set the binary to e.g. "/home/you/.nix-profile/bin/claude".

Startup notice: the first interactive session to reach Claude Code lists whichever of provider.plan and askClaude.enabled you have left unset, then records startupNoticeShown (the date, YYYY-MM-DD) in the global config so it doesn't nag again.

Extension providers and models.json: pi's modelOverrides in ~/.pi/agent/models.json do not currently apply to extension-registered providers (like claude-bridge). Overriding contextWindow or other fields requires editing src/models.ts directly — to pin a model to 200K, use provider.forceTwoHundredK instead.

Tests

npm run test:unit for offline tests (tests/unit-*.mjs: queue, import, skills).

npm test for the full suite, which adds integration tests that hit APIs (tests/int-*.{sh,mjs}: smoke, multi-turn, cache, session-resume, session-rebuild, tool-message). Set CLAUDE_BRIDGE_TESTING_ALT_MODEL in .env.test for the alt-provider smoke test (e.g. openrouter/z-ai/glm-4.7-flash).

Integration tests spawn real pi and Claude Code subprocesses, so they need write access to ~/.claude for CC's session state — a sandbox that blocks it makes the next turn's --resume fail with No conversation found with session ID. The RPC harness probes for this at startup and fails fast.

Debugging

Set CLAUDE_BRIDGE_DEBUG=1 to enable debug output:

• Bridge log at ~/.pi/agent/claude-bridge.log — every provider call, session sync decision, tool result delivery, and CC's stderr. Override location with CLAUDE_BRIDGE_DEBUG_PATH.
• Per-query Claude Code CLI logs at ~/.pi/agent/cc-cli-logs/<timestamp>-<tag>-<seq>.log — the CC subprocess's own debug stream, one file per query() call. Tags are provider (main turn) or askclaude (sub-delegation). Useful when a resume fails or CC misbehaves internally — shows the CLI's own view of session loading, API requests, and tool calls.

When filing a bug about a session-resume failure (e.g. "No conversation found"), the most useful attachments are the syncResult: lines from the bridge log plus the matching cc-cli-logs/ file for the failing query.

Known issues

Sessions get rebuilt more often than they need to be, and a rebuild is expensive. The bridge rewrites Claude Code's session from pi's history whenever pi's messages move underneath it — after an abort, /compact, tree navigation, or an API error. Measured over this repo's own bridge log, a rebuild boundary loses the prompt cache roughly 58% of the time against 26% for a plain resume, so an abort-heavy session costs noticeably more than a clean one. Aborts alone are 46% of rebuilds.

Files Claude Code edits are not carried across a rebuild. CC records the post-edit contents as an edited_text_file attachment; those aren't carried, because they hang off a tool-result record rather than a prompt and so have no stable position to restore them to. The edit itself survives — it's in the history as a tool call and its result — so this costs Claude the file snapshot, not the knowledge that it made the change. @file expansions are carried.

On pi 0.86 with bridge 0.7.0 or older, every new session fails. The symptoms are WARNING session verify: file missing after save and then No conversation found with session ID on the next turn: pi 0.86 moved the system prompt and tool set into role:"system" transcript messages, which the older bridge read as a one-message history. Upgrade the bridge rather than downgrading pi — on 0.86 the old bridge also serves no tools, so a turn that does go through looks normal while the model writes tool calls out as prose instead of calling anything.

Exported Anthropic environment variables override the Claude Code child (issue #107). The bridge passes the ambient environment through, so an ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN exported for another gateway (a corporate proxy, LiteLLM) redirects Claude Code as well, and every turn fails with that gateway's auth error. Unset them for the pi process.