pi-claude-bridge

Fork note. @viniciosrab/pi-claude-bridge is an automated mirror of pi-claude-bridge by Eli Dickinson (elidickinson/pi-claude-bridge), rebuilt for each upstream release with fork-only additions: the provider.loadClaudeSettings option (upstream PR #142) and the provider.rateLimitWarnings option. Versions match upstream; a X.Y.(Z+1)-fork.N version is upstream X.Y.Z with newer fork-only changes. Licensed MIT; original copyright and credit belong to Eli Dickinson. Fork: viniciosrab/pi-claude-bridge.

Pi extension that integrates Claude Code via the Agent SDK. Originally based on claude-agent-sdk-pi by Prateek Sunal.

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.86.1 or newer.

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 everything works like normal in pi. Bash commands get Claude Code's 120-second default timeout since pi's bash has none. Skills are forwarded to Claude Code's system prompt, and steering mid-turn reaches Claude at the next tool boundary.

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.

1M Context: Fable 5/5.1, Opus 5.5/5/4.8/4.7, and Sonnet 5.5/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 — set provider.plan and/or provider.longContextExtraUsage as described in Configuration.

AskClaude Tool

Deprecated: AskClaude is an opt-in legacy tool and may be removed in a future release. You should set askClaude.enabled to true (see Configuration) to use it. You can recreate similar functionality with one of the many Pi subagent extensions.

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".

Notices: the startup notice points out when provider.plan is unset and records startupNoticeShown in the global config. There's also a deprecation notice on first use of AskClaude that records its display date as askClaudeDeprecationShown.

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. npm test adds integration tests that hit APIs; set CLAUDE_BRIDGE_TESTING_ALT_MODEL in .env.test for the alt-provider smoke test.

Integration tests spawn real pi and Claude Code subprocesses and need write access to ~/.claude — a sandbox that blocks it makes --resume fail with No conversation found with session ID.

Debugging

Set CLAUDE_BRIDGE_DEBUG=1 to enable debug output:

• Bridge log at claude-bridge.log in pi's agent dir (PI_CODING_AGENT_DIR, default ~/.pi/agent) — provider calls, session sync decisions, tool results, CC stderr. Override location with CLAUDE_BRIDGE_DEBUG_PATH.
• Per-query CC CLI logs at cc-cli-logs/<timestamp>-<tag>-<seq>.log in the same directory — the subprocess's own debug stream; tag is provider or askclaude. Shows CC's 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.

Compatibility with other extensions

Which injection routes reach Claude Code

The bridge forwards pi's structured parts — project context files, skills, custom prompt, appended instructions, and custom prompt sections (systemPromptOptions.sections) — and drops the rest. Measured against the request body (diag/capture-proxy.mjs):

Route	Reaches Claude Code
before_agent_start -> message	Yes, as literal prompt text in the user turn
context editing the last user message	Yes, as literal prompt text
--append-system-prompt	Yes, with pi's appended instructions
context_with_system editing the system message	Yes when it wraps pi's prompt; the turn fails when it replaces one
before_agent_start -> systemPromptOptions.sections	Yes, one <name> block per section
before_agent_start -> systemPrompt	No, dropped

Two traps. Returning systemPrompt from before_agent_start makes pi replace the whole system prompt, discarding any context_with_system edit in the same run — only one reaches the request. And system-prompt edits work by wrapping: replacing pi's prompt leaves the bridge with nothing to match, so it refuses the turn rather than send Claude Code a request missing your context files, skills and custom instructions. The error names the closest known prompt and where it diverged.

To add instructions, use message, context, or a system-message edit that keeps pi's prompt intact.

Hooks written for Claude Code

~/.claude/settings.json hooks fire inside bridge turns, so a hook injecting Claude-specific guidance duplicates what pi's extensions already provide. pi sets PI_CODING_AGENT=true for child processes, including the Claude Code child; a hook can skip itself on that:

[ -n "$PI_CODING_AGENT" ] && exit 0

Hooks do not fire on isolated summary queries.

Compaction and branch summaries

pi runs compaction and branch summaries natively. The bridge routes their cacheRetention: "none" calls to isolated Claude Code queries, leaving the live session untouched until pi completes the history rewrite. Other extensions can provide summaries through pi's hooks.

System prompt rejections

Other extensions can change the system prompt. When the result still contains pi's built-in system prompt text, or the two documentation paths that Anthropic looks for (docs/custom-provider.md in the same prompt with docs/packages.md), the bridge stops the turn instead of sending it, since Anthropic may otherwise bill these requests as Extra Usage. Fix the source extension before retrying; CLAUDE_BRIDGE_DEBUG=1 writes the full prompt to the bridge log when this happens.

Plan usage for footers and quota extensions

The bridge does not show plan usage itself. Claude Code sends a rate_limit_event when a usage window changes, and the bridge passes it to pi's after_provider_response event as anthropic-ratelimit-unified-* headers. Events are not tied to one response: one that arrives after a turn has ended on a tool call is reported on the next provider call, and only the latest is kept. The headers use the names that the Anthropic API uses (for example anthropic-ratelimit-unified-5h-utilization). The bridge sends only the headers that it can make from the event: the status, the reset time, the representative claim, the overage status and reset, and the utilization and reset of each window. The status code is always 200. An extension that reads these headers for the built-in anthropic provider can also accept claude-bridge without other changes.

Using claude bridge with @gotgenes/pi-subagents

Requires the following in ~/.pi/agent/subagents.json:

{"promptInheritance": {"claude-bridge": "portable"}}

Known issues

A session rebuild re-sends the whole conversation. The bridge rewrites Claude Code's session from pi's history whenever the two diverge — after an abort, /compact, tree navigation, an API error, or on returning to a session — and the next request usually misses the prompt cache for everything past the system prompt. Abort-heavy sessions cost noticeably more.

Files Claude Code edits are not carried across a rebuild. The edit itself survives in the history as a tool call and result — what's lost is the post-edit file snapshot. @file expansions are carried.

System prompt changes mid-session may not reach the model. The bridge keeps Claude Code's default prompt recording: project context (AGENTS.md/CLAUDE.md), skills, and extension-written instructions are captured on the first request and reused on resume. This keeps the cached prefix stable, but later changes may not take effect until a rebuild or compaction. Start a new session if updated instructions must take effect immediately.

Exported Anthropic environment variables override the Claude Code child (issue #107). An exported ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN redirects Claude Code to that gateway and every turn fails with its auth error. Unset them for the pi process.

Fork-only options

Set under provider in the bridge config, alongside the options in Configuration (@viniciosrab/pi-claude-bridge only):

• loadClaudeSettings — load Claude Code's user/project/local settings in the provider's Claude Code subprocess (default true). Set false to skip them: settings-sourced hooks and plugins no longer run on every turn, which can noticeably cut tokens and latency when you have many configured. It also drops settings-sourced env and apiKeyHelper, so keep the default if you rely on those (e.g. Bedrock/Vertex setup in settings.json). OAuth login, pi tools and extensions are unaffected. Applies only to the provider path; AskClaude always loads settings.
• rateLimitWarnings — show Claude rate-limit notices in pi (default true): the usage warning at each 5% step and the notice with the reset time when a request is rejected. Set false to hide both. A rejected request's failure is still named as a rate limit (so fallback chains keep working).