@benvargas/pi-claude-code-use

pi-claude-code-use keeps Pi's built-in anthropic provider intact and applies the smallest payload changes needed for Anthropic OAuth subscription use in Pi.

It does not register a new provider or replace Pi's Anthropic request transport. Pi core remains in charge of OAuth transport, headers, model definitions, and streaming.

What It Changes

When Pi is using Anthropic OAuth, this extension intercepts outbound API requests via the before_provider_request hook and:

• System prompt rewrite -- rewrites a small set of Pi-identifying prompt phrases in system prompt text:
  • pi itself → the cli itself
  • pi .md files → cli .md files
  • pi packages → cli packages Preserves Pi's original system[] structure, cache_control metadata, and non-text blocks.
• Tool filtering -- passes through core Claude Code tools, Anthropic-native typed tools (e.g. web_search), and any tool prefixed with mcp__. Unknown flat-named tools are filtered out.
• Companion tool remapping -- renames known companion extension tools from their flat names to MCP-style aliases (e.g. web_search_exa becomes mcp__exa__web_search). Duplicate flat entries are removed after remapping.
• tool_choice remapping -- if tool_choice references a flat companion name that was remapped, the reference is updated to the MCP alias. If it references a tool that was filtered out, tool_choice is removed from the payload.
• Message history rewriting -- tool_use blocks in conversation history that reference flat companion names are rewritten to their MCP aliases so the model sees consistent tool names across the conversation.
• Companion alias registration -- at session start and before each agent turn, discovers loaded companion extensions, captures their tool definitions via a jiti-based shim, and registers MCP-alias copies so Anthropic sees Claude Code-compatible names.
• Managed tool-call unaliasing -- when the model calls an MCP alias registered by this extension, rewrites the finalized toolCall name back to the original flat tool name during message_end, before Pi resolves execution. Direct MCP tools from other extensions are left untouched.
• Alias activation tracking -- auto-activates MCP aliases when their flat counterpart is active under Anthropic OAuth. Tracks provenance (auto-managed vs user-selected) so that disabling OAuth only removes auto-activated aliases, preserving any the user explicitly enabled.

Non-OAuth Anthropic usage and non-Anthropic providers are left completely unchanged.

Install

pi install npm:@benvargas/pi-claude-code-use

Or load it directly without installing:

pi -e /path/to/pi-packages/packages/pi-claude-code-use/extensions/index.ts

Usage

Install the package and continue using the normal anthropic provider with Anthropic OAuth login:

/login anthropic
/model anthropic/claude-opus-4-6

No extra configuration is required.

Environment Variables

| Variable | Description | |---|---| | PI_CLAUDE_CODE_USE_DEBUG_LOG | Set to a file path to enable debug logging. Writes two JSON entries per Anthropic OAuth request: one with "stage": "before" (the original payload from Pi) and one with "stage": "after" (the transformed payload sent to Anthropic). | | PI_CLAUDE_CODE_USE_DISABLE_TOOL_FILTER | Set to 1 to disable tool filtering. System prompt rewriting still applies, but all tools pass through unchanged. Useful for debugging whether a tool-filtering issue is causing a problem. |

Example:

PI_CLAUDE_CODE_USE_DEBUG_LOG=/tmp/pi-claude-debug.log pi -e /path/to/extensions/index.ts --model anthropic/claude-sonnet-4-20250514

Companion Tool Aliases

When these companion extensions from this monorepo are loaded alongside pi-claude-code-use, MCP aliases are automatically registered and remapped:

| Flat name | MCP alias | |---|---| | web_search_exa | mcp__exa__web_search | | get_code_context_exa | mcp__exa__get_code_context | | firecrawl_scrape | mcp__firecrawl__scrape | | firecrawl_map | mcp__firecrawl__map | | firecrawl_search | mcp__firecrawl__search |

How companion discovery works

The extension identifies companion tools by matching sourceInfo metadata that Pi attaches to each registered tool:

1. baseDir match -- if the tool's sourceInfo.baseDir directory name matches the companion's directory name (e.g. pi-exa-mcp).
2. Path match -- if the tool's sourceInfo.path contains the companion's scoped package name (e.g. @benvargas/pi-exa-mcp) or directory name as a path segment. This handles npm installs, git clones, and monorepo layouts where baseDir points to the repo root rather than the individual package.

Once a companion tool is identified, its extension factory is loaded via jiti into a capture shim to obtain the full tool definition, which is then re-registered under the MCP alias name. Those alias copies are model-facing compatibility shims; when the assistant actually calls one of these managed aliases, pi-claude-code-use rewrites the finalized toolCall back to the original flat name before Pi executes the tool. This preserves the source extension's original execute closure and state.

User-Defined Tool Aliases

To register MCP-style aliases for flat-named tools from other installed extensions, create ~/.pi/agent/extensions/pi-claude-code-use.json (global) or <project>/.pi/extensions/pi-claude-code-use.json (project). Schema:

{
  "toolAliases": [
    ["subagent", "mcp__subagent__run"],
    ["linear_search", "mcp__linear__search"]
  ]
}

Each entry maps an existing flat Pi tool name to the MCP-style name Anthropic should see. Use the flat tool name exactly as the source extension registers it; choose an MCP alias in the form mcp__<namespace>__<tool>.

Aliases registered through this config are treated the same as the built-in companion aliases: Anthropic sees the MCP-style name, but managed alias calls are canonicalized back to the flat source tool before local execution. MCP-style tools that are provided directly by another extension are not rewritten unless pi-claude-code-use registered that same alias.

The project file replaces the global file as a whole. Set "toolAliases": [] in the project file to disable inherited globals.

Core Tools Allowlist

The following tool names always pass through filtering (case-insensitive). This list mirrors Pi core's claudeCodeTools in packages/ai/src/providers/anthropic.ts:

Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, EnterPlanMode, ExitPlanMode, KillShell, NotebookEdit, Skill, Task, TaskOutput, TodoWrite, WebFetch, WebSearch

Additionally, any tool with a type field (Anthropic-native tools like web_search) and any tool prefixed with mcp__ always passes through provider-request filtering. Direct MCP tools remain direct MCP tools; only aliases registered by pi-claude-code-use are rewritten back to flat names before local execution.

Guidance For Extension Authors

Anthropic's OAuth subscription path appears to fingerprint tool names. Flat extension tool names such as web_search_exa were rejected in live testing, while MCP-style names such as mcp__exa__web_search were accepted.

If you want a custom tool to survive Anthropic OAuth filtering cleanly, prefer registering it directly under an MCP-style name:

mcp__<server>__<tool>

Examples:

• mcp__exa__web_search
• mcp__firecrawl__scrape
• mcp__mytools__lookup_customer

If an extension keeps a flat legacy name for non-Anthropic use, it can also register an MCP-style alias alongside it. pi-claude-code-use already does this centrally for the known companion tools in this repo, but unknown non-MCP tool names will still be filtered out on Anthropic OAuth requests.

Notes

• The extension activates for all Anthropic OAuth requests regardless of model, rather than using a fixed model allowlist.
• Non-OAuth Anthropic usage (API key auth) is left unchanged.
• In practice, unknown non-MCP extension tools were the remaining trigger for Anthropic's extra-usage classification, so this package keeps core tools, keeps MCP-style tools, auto-aliases the known companion tools above, and filters the rest.
• Pi may show its built-in OAuth subscription warning banner even when the request path works correctly. That banner is UI logic in Pi, not a signal that the upstream request is being billed as extra usage.