Pi Claude DirectSDK

Use Claude inside Pi through the official Claude Agent SDK and the unmodified Claude Code executable. Pi owns the transcript, tools, approvals, and retries; Claude Code supplies subscription authentication and the model.

One Claude Code session serves each Pi conversation. Assistant output streams through as it arrives, tool calls return to Pi for authorization and execution, and the same session continues with those results. Claude Code runs with no native tools, no settings, no skills, and no MCP servers except the one Pi supplies.

Requirements

• Pi. The current maintainer installation is Pi 1.3.0; see verification details.
• Node 20 or later for Node-based Pi installations and local development. Compiled Pi uses its bundled runtime.
• Claude Code installed and reachable. The SDK handshake tests the installed version at each session start, so this project does not pin a version range. Claude Code 2.1.281 is the version under test.
• A Claude paid plan. The free plan excludes the CLI.
• A Claude Code login via claude auth login.

Install

Sign in through the official CLI:

claude auth login

Install the extension from npm, or from Git instead, but not both:

pi install npm:pi-claude-directsdk
pi install git:github.com/joaomj/pi-claude-directsdk  # alternative source

Start or restart interactive Pi, open /model, and wait for the DirectSDK catalog refresh. On a fresh install, this step must complete before selecting the model from the command line; later invocations can use the saved catalog, for example pi --model claude-directsdk/haiku.

DirectSDK uses the CLI login, not the Pi Anthropic login.

The model catalog does not guarantee account entitlement. Start with haiku for a small request. Models that require usage credits can incur separate charges, and DirectSDK cannot undo a charge that Claude Code already reported. See usage credits.

Test a local checkout

A local run needs no release and no version bump. Run the extension directly from the checkout:

pi -e ./extensions/claude-directsdk/index.ts --model claude-directsdk/haiku

Pi loads the extension for that invocation only and leaves your settings unchanged. To keep it installed while developing, add the checkout itself:

pi install ./          # registers this directory as an extension source
pi remove ./           # removes it again

Two checks need no Pi session:

npm test               # offline: scripted Claude Agent SDK runtime, no model calls
npm run smoke          # two real model calls against your own Claude Code login

npm run smoke proves the tool round trip on the real binary: the first call must return a tool call, and the second must answer from the tool result Pi supplies. It closes the session it opened. Both commands are described in testing.md.

Upgrade

pi update npm:pi-claude-directsdk                              # npm installation
pi update git:github.com/joaomj/pi-claude-directsdk            # Git installation

Run only the command for your source; pi list shows installed declarations. Version-pinned sources remain pinned when updated, so change a pin or switch sources with pi remove <old-source> and a fresh install. Restart Pi afterwards, then open /model and wait for catalog refresh.

Comparison with other Claude providers

Three extensions expose the Claude subscription through Claude Code while Pi owns the session. This table reflects DirectSDK main, pi-claude-bridge 0.9.3, and pi-claude-code 0.1.0 (experimental) as of October 23, 2026.

pi-claude-bridge requires Pi >=0.86.1. DirectSDK accepts the installed Claude Code version and fails with the CLI's own message when the SDK handshake cannot complete. All three use a Claude Code login, draw on the same subscription, and can be affected by Anthropic billing changes. None has a matched performance benchmark. DirectSDK's own numbers: 37,526 prompt tokens and a $0.0293 cost estimate against claude -p --resume's 88,700 and $0.0684 for the same three turns, with 98.8 to 98.9 percent cache-read share on continued turns. The plan window itself could not be measured, because its percentage decays inside the same window, so the cost saving is not evidence of a quota saving either way.

Documentation

• Usage and configuration: local checkout, environment settings, costs, and diagnostics.
• Architecture: session lifecycle, prompt composition, tool bridge, and rebuild rules.
• Troubleshooting: missing CLI, login, and conflicting environment settings.
• Testing and startup: what each check proves, and what the extension does at load.
• Architecture decision: why this transport uses the official Agent SDK.

Issues and security

Bug reports, feature requests, and questions are welcome through issue forms. This project does not accept unsolicited public pull requests; see contribution guidance. Report vulnerabilities privately as described in the security policy.

Acknowledgments and license

Behavioral reference: Hermes Claude Subscription DirectSDK (MIT). This project copies its behavior contract, not its code. DirectSDK is MIT licensed; see LICENSE.