pi-claude-code-tui

An experimental Pi provider that runs Claude Code's interactive terminal UI in a pseudo-terminal (PTY), rather than claude -p.

Why: Headless claude -p has been reported to use roughly 1.8× more of the five-hour usage window per token than the interactive UI. This provider drives the interactive UI instead. It has not been measured here, and usage behavior is not guaranteed.

Pi manages conversation history, approvals, and tool execution. Claude Code handles model communication. Compatible processes are reused, with Pi's conversation restored for each model call.

Requirements

• Node.js 24.21 or later, Pi, and Claude Code.
• Python 3.9 or later as python3, with os.forkpty, os.waitid, and os.WNOWAIT.
• Linux or macOS. Tested on WSL2 with Claude Code 2.1.316 and Haiku 5.5; macOS is untested, and native Windows is unsupported.

Install

pi install npm:@minty1st/pi-claude-code-tui

Or install the latest source from GitHub with pi install git:github.com/MINTY1st/pi-claude-code-tui. Use the scoped name above: the unscoped npm name pi-claude-code-tui belongs to an unrelated package.

Restart Pi after installation. Disable any other extension registering the same Claude Code provider.

Usage

Authenticate Claude Code:

claude auth login

Run claude once in your working directory, complete folder trust, and exit. This extension does not approve folder trust automatically by default.

Start Pi and select Claude Code Subscription (Experimental) in the model picker. Use /claude-code-status inside Pi to check detection and authentication.

To try a source checkout without other extensions:

pi -ne -e /absolute/path/to/pi-claude-code-tui/src/index.ts \
  --provider claude-code --model haiku

Configuration

Claude Code manages authentication. The extension does not read or copy credential files; authenticated request headers pass through a local relay.

Pi's request timeout (retry.provider.timeoutMs, defaulting to httpIdleTimeoutMs, 300 seconds) is an idle timeout: a turn fails only when nothing arrives from upstream for that long. A turn that keeps streaming, such as a long review, can run past it. The screen is not used as a sign of progress, because Claude Code's spinner redraws it every second even when the turn is stuck.

Connection failures, dropped connections and idle timeouts are reported with wording that Pi's automatic retry recognizes (connection error, connection lost, timed out), so Pi retries the turn even though Claude Code's own retries stay disabled (CLAUDE_CODE_MAX_RETRIES=0). 4xx responses, billing errors and malformed streams are reported without that wording and are not retried. A tool call outside Pi's current tool list is passed to Pi as is, and Pi answers the model with a "Tool ... not found" tool result instead of failing the turn.

Limitations

• Claude Code updates may break terminal-output detection. One live test timed out; retries passed, but the cause remains unknown.
• Pi's prompt is carried in a user message, not as system-level instructions. Complex tool schemas may be simplified; mid-conversation tool changes work only on supported models.
• Cross-provider tool-call IDs are normalized for Anthropic on outgoing replay only; saved history is unchanged.
• claude-opus-5-5 and claude-fable-5-1 reject both disabled and between_tools for turning thinking off, so requests with reasoning off fail with HTTP 400 on those models. claude-sonnet-5-5 uses between_tools; other models use disabled.
• Thinking text shown in Pi is an API-generated summary and may be in English regardless of the conversation language.
• Each call replays Pi's history after /clear, rather than resuming a native Claude Code conversation. Only the first upstream request is forwarded; additional requests in that call are rejected.
• One process is cached per session, two across the extension, with a 15-minute idle expiry. When the cache is full, a new session closes the least recently used idle process to take its place; if every cached process is busy, the new session uses a disposable worker. Concurrent requests and requests without a session ID use disposable workers.
• Cleanup covers the same process group only, not descendants escaping with setsid/setpgid or SIGKILL of the PTY helper itself.

Documentation

• Architecture: request paths, the relay, and a source map
• Turn lifecycle: how the end of a TUI turn is detected, timeouts, and aborts
• Errors and retries: response checks and which failures Pi retries
• Worker reuse: when a Claude Code process is reused and how per-turn values are applied

Development

From a source checkout:

npm ci
npm test
npm run check
npm pack --dry-run

Tests use a fake Claude Code and local upstream, not the real model service. PTY tests start real child processes and require python3.

scripts/verify-turn-body.mts and scripts/verify-thinking-summaries.mts send a few real requests through Claude Code to check behavior that the fake cannot reproduce (request bodies, beta headers, cache reads, thinking text). They use your Claude plan; run them only when changing those areas.

The CI workflow runs npm ci --ignore-scripts, npm test, and npm run check on Node 24.22.2 for every pull request and every push to main.

Publishing

An owner-pushed vX.Y.Z tag triggers the publishing workflow. The tagged commit must be in main, and the tag, manifest, and lockfile versions must match. Tests and type checks run without publishing credentials; a separate job publishes the verified tarball. After the package is published, a third job creates the GitHub Release for the tag with generated notes; only that job has contents: write. The notes group pull requests by the labels fix, feature, docs, and ci/chore as defined in .github/release.yml.

One-time npm setup: in this package's Settings → Trusted Publisher, select GitHub Actions, set the owner and repository to this repository, and enter publish.yml as the workflow filename. Allow direct publishing; leave the environment name empty. No npm token or GitHub secret is needed. Keep repository write access limited to the owner. The workflow also checks the triggering actor, but cannot distinguish the owner's terminal from an agent using the owner's credentials.

After merging a version update, explicitly request a release or push its tag:

git switch main
git pull --ff-only origin main
git tag vX.Y.Z
git push origin vX.Y.Z

Only stable versions are supported. Existing npm versions cannot be overwritten. Do not create a release tag until the trusted publisher is configured.

Credits and license

• earendil-works/pi-claude-code, by Armin Ronacher — the upstream provider, conversation conversion, and relay implementation.
• yetone/magpie, by yetone — reference for PTY operation, terminal queries, input settling, and readiness detection. This package uses relay-based response capture rather than magpie's JSONL/tap approach.

An unofficial fork, licensed under MIT. Original copyright notices are preserved; see third-party notices for magpie's full MIT notice.