picc-claude-shim

Drop-in replacement for the Claude Code CLI, by disguising pi as Claude Code. Part of picc, a pi agent setup mirroring Claude Code's harness. Softwares built upon Claude Code, like hapi and T3 Code, can directly replace Claude Code with pi.

The shim parses the Claude-flavored CLI flags, creates a pi AgentSession, and translates bidirectionally between pi session events and Claude Code's stream-json wire protocol (system/assistant/result/control_request/control_response). It also mirrors each turn into a Claude/hapi-compatible session JSONL and reports a Claude-style version, so hosts that probe claude --version or scan ~/.claude/projects/**/<session-id>.jsonl see exactly what they would see against a real Claude Code install.

Modes

| Mode | Invocation | Purpose | |------|------------|---------| | stream-json | --output-format stream-json --input-format stream-json | The primary host target. Bidirectional NDJSON over stdin/stdout; speaks the Claude Code SDK protocol and bridges a live pi session. | | json | --output-format json | One-shot single-JSON-object output. With --json-schema <schema> emits {"structured_output": <value>} (t3code's commit/PR/title text-generation parser); without, emits a single Claude result message. Prompt arrives inline or on stdin. | | print | --print <prompt> (or bare -p) | One-shot text output. Streams the assistant's final text to stdout and exits 0. Used for quick smoke tests. | | local (TTY) | (default, no JSON flags) | Not supported. Emits an explicit error and exits 1 — pi's interactive TUI uses Ink and would conflict with a host's terminal handling. |

--version and --help are answered by a fast JS path (bin/claude.js) without loading the pi runtime. At package installation, the shim fetches the latest official Claude Code GitHub release once and caches its version. That cached version is used by --version, the startup banner, system/init, and session JSONL metadata. Normal shim invocations never refresh it; a failed install-time fetch preserves an existing cache or falls back to the bundled version.

T3 Code's no-prompt capability check uses a lightweight protocol path, so account metadata is available without loading pi or waiting for the full runtime to initialize.

Install

Install as a pi package — one command does the whole job:

pi install npm:@ladbabynpm/picc-claude-shim

pi records npm:@ladbabynpm/picc-claude-shim in ~/.pi/agent/settings.json#packages and installs the package itself into its managed npm directory:

~/.pi/agent/npm/node_modules/@ladbabynpm/picc-claude-shim/

pi loads the package's pi.extensions manifest directly from there, so no manual registration is needed. The package's postinstall hook (install.js) additionally materializes a dedicated, deterministic launcher directory that does not collide with other software and never changes PATH:

~/.pi/agent/extensions/picc-claude-shim/bin/

That directory is the recommended thing to point third-party applications at, because it is guaranteed to exist: if a package manager skips the postinstall hook, the shim recreates it on the first real (non---version) invocation. Both locations are valid entry points.

On Windows, configure third-party applications to execute:

~/.pi/agent/extensions/picc-claude-shim/bin/claude.exe

The installer writes picc-claude-shim-root.txt beside the executable so the copied native launcher can resolve its npm-managed runtime after package upgrades. On POSIX systems, configure ~/.pi/agent/extensions/picc-claude-shim/bin/claude instead.

Resolving the pi runtime

The drop-in binary runs outside pi, so it locates the @earendil-works/pi-coding-agent install itself, in this order (first match wins):

1. PICC_CLAUDE_SHIM_PI_DIR — explicit override to the pi-coding-agent directory (highest priority).
2. the nearest node_modules/@earendil-works/pi-coding-agent walking up from the package.
3. a global Bun root ($BUN_INSTALL/install/global/node_modules, ~/.bun/install/global/node_modules) — bun-compiled hapi runners commonly live here.
4. the global npm root (npm root -g).
5. pi's managed install, resolved through ~/.pi/agent/install/current-version to ~/.pi/agent/install/releases/<version>/node_modules, then legacy pi-managed npm roots (~/.pi/agent/npm/node_modules, ~/.pi/agent/node_modules, ~/.pi/node_modules).

If none are found, the shim prints a clear error showing the PICC_CLAUDE_SHIM_PI_DIR override. Set that variable in the environment of whatever process spawns claude (e.g. the hapi runner) to point at your pi install:

PICC_CLAUDE_SHIM_PI_DIR=/path/to/node_modules/@earendil-works/pi-coding-agent

Flags

Parsed by parseClaudeArgs (src/args.ts). Unrecognized flags are collected and reported on the startup banner but do not fail the run.

| Flag | Effect | |------|--------| | --output-format stream-json / --input-format stream-json | Enable stream-json mode. | | --output-format json | Enable json (one-shot) mode. | | --print <prompt> / -p | Enable print mode. Bare -p reads the prompt from stdin. | | --permission-prompt-tool stdio | Accepted. The permission gate is in practice open for any non-bypassPermissions mode. | | --permission-mode <mode> / --dangerously-skip-permissions | bypassPermissions closes the gate entirely; other modes are forwarded to PICC_PERMISSION_MODE for @ladbabynpm/picc-permission-modes. | | --system-prompt <text> | Replace the pi system prompt. | | --append-system-prompt <text> | Append to the pi system prompt. | | --resume <id> | Open the existing pi session with that id (falls back to a fresh session if not found). | | --continue | Continue the most recent pi session in the cwd. | | --allowed-tools <list> / --disallowed-tools <list> | Permission rules, not tool activation: --allowed-tools pre-approves matching tool names; --disallowed-tools removes matching pi tools. | | --model <id> | Parsed, surfaced in system/init until the real pi model is known. See Known limitations. | | --max-turns <n> | Parsed but not enforced. | | --include-partial-messages | When set, the translator emits partial assistant message updates. | | --json-schema <schema> | (json mode only) Emit {"structured_output": <value>} decoded against the schema. |

Tool name mapping

Mappings in src/tool-names.ts are case-insensitive in both directions to match picc's registered tool names, which may be lowercase (read, bash, grep) or PascalCase (Read, Edit, Glob). pi find maps to Claude Glob (picc-glob accepts both Glob and find); the other built-ins map identity-modulo-case. Unknown tools (TodoWrite, WebSearch, etc.) have no pi equivalent — if a tool-call gate asks permission for one, the shim replies with control_response{behavior:"deny"}.

| pi (canonical) | Claude wire name | |----------------|------------------| | read | Read | | write | Write | | edit | Edit | | bash | Bash | | grep | Grep | | find | Glob | | ls | LS |

Testing

Run the unit tests:

node test/run-all.mjs

Tests cover:

• args.test.ts — flag parsing (--output-format, --permission-prompt-tool, etc.)
• tool-names.test.ts — pi ↔ Claude tool name mapping (case-insensitive)
• session-jsonl.test.ts — hapi JSONL writer
• session-resume.test.ts — resume id resolution
• cost.test.ts — usage + cost synthesis
• permission-gate.test.ts — when the permission gate is open/closed
• translator.test.ts — stdin → pi calls
• translator-out.test.ts — pi events → Claude NDJSON (result fields, control_request)
• compact.test.ts — /compact parsing and interception
• skills.test.ts — skill discovery + expansion
• structured-output.test.ts — --json-schema value extraction

entry.e2e.test.ts is a separate live-backend test (needs a configured pi model + API key) and is not part of run-all.mjs. Run it with:

node test/run-e2e.mjs

Files

picc-claude-shim/
├── package.json         # @ladbabynpm/picc-claude-shim; jiti dep, pi peer deps
├── tsconfig.json
├── install.js           # postinstall entry point
├── installer-lib.mjs    # copies explicit launchers under the pi extension directory
├── README.md
├── scripts/
│   ├── build-exe.mjs    # build native claude.exe (Claude Agent SDK spawn path on Windows)
│   └── claude_launcher.c
├── bin/
│   ├── claude.js        # Node entry; --version/--help fast path, else imports src/entry.ts via jiti
│   ├── claude.cmd       # Windows entry template (install.js fills in the path)
│   ├── claude           # POSIX entry
│   ├── claude.exe       # native entry (built by scripts/build-exe.mjs)
│   └── entry-slow.mjs   # jiti loader; aliases pi-coding-agent to pi's install
├── src/
│   ├── index.ts         # no-op extension factory; registers --claude-shim-install flag
│   ├── entry.ts         # orchestrator: args → pi session → protocol loop (all modes)
│   ├── args.ts          # parseClaudeArgs — Claude-flavored argv parser
│   ├── translator.ts    # bi-directional event/message translation
│   ├── session-jsonl.ts # hapi-compatible session JSONL writer
│   ├── tool-names.ts    # case-insensitive pi ↔ Claude tool name mapping
│   ├── cost.ts          # synthesizeUsageAndCost from pi's SessionStats
│   ├── skills.ts        # Claude skill discovery + expansion
│   ├── structured-output.ts # --json-schema value extraction
│   └── version.js       # version string the shim impersonates
└── test/                # unit + e2e tests (see Testing)

Known limitations

• --model is parsed and surfaced in system/init but does not select a model; pi picks from ~/.pi/agent/settings.json#defaultModel. Honoring arbitrary provider IDs requires plumbing through pi's ModelRuntime registry.
• --max-turns is parsed but not enforced; the session runs as many turns as the agent decides.
• Hook forwarder commands (the hapi hook-forwarder invocation Claude Code runs on SessionStart) are not triggered. Hosts tolerate this when system/init and the JSONL file are both present.

Differences from Claude Code

These are intentionally out of scope for picc-claude-shim.

• No local (TTY) mode — stream-json, json, and print only.
• No hooks — --settings SessionStart hook forwarding is not invoked.
• No --model selection — pi's default model is used.
• No --max-turns enforcement.
• Skill inline bash — Claude Code executes inline !`…` injections in a skill body before sending; the shim forwards the substituted body as-is and lets pi's agent run such commands via its own tools.
• No .agents/skills scan — only the user and project .claude/skills roots Claude Code verifies are scanned.
• No --output-format stream-json partial streaming by default — set --include-partial-messages to emit partial assistant updates.