PiCC

Run projects built for Claude Code — unchanged — on GPT/Codex models, from your ChatGPT subscription.

Many projects carry a .claude/ corpus: CLAUDE.md hierarchies, skills, subagents, settings.json permissions and hooks, rules, and workflows that rely on worktree isolation and parallel sessions. PiCC is an agentic harness that reads and honors those Claude-format artifacts natively on GPT models, with no changes to the target project.

It is built as an extension bundle on Pi (MIT), which already solves the two hardest problems — spending a ChatGPT/Codex subscription and abstracting the model provider. PiCC adds the Claude Code compatibility layer on top.

Quick start

PiCC requires Node.js 22.19 or newer, npm, and git. Windows also requires Git Bash from Git for Windows. Install the current release, then launch it from the Claude Code project you want to use:

npm install --global @arnedeutsch/picc
cd <path-to-your-claude-code-project>
picc
# /login  → connect ChatGPT Plus/Pro (one time)
# /model  → pick a GPT/Codex model
# /doctor → review this project's compatibility findings

If npm cannot resolve @arnedeutsch/picc, use the source checkout instead:

git clone https://github.com/ArneDeutsch/PiCC.git
cd PiCC
npm run setup

Then change to the target project and run picc as above. Installation variants, exact versions, Windows notes, authentication, and updates are in the user guide. Release archives and notes are on GitHub Releases.

→ Full documentation: doc/user-guide.md · Architecture · Supported features · Testing · Contributing

What it does

• Skills — .claude/skills and legacy .claude/commands, with progressive disclosure, argument substitution, and shell injection.
• Subagents — .claude/agents/*.md and the built-in agent types, with description-driven routing, parallel background fan-out (nesting is opt-in via subagents.maxDepth), per-agent tool gating, and worktree isolation.
• Subagent observability — a live status panel of the whole agent tree with a drill-down per agent (prompt, structured live detail, final answer, stop/dismiss/steer), plus condensed, expandable per-agent records in the chat transcript.
• Worktrees — EnterWorktree/ExitWorktree with a real session-cwd swap and a Windows-tolerant lifecycle, for parallel sessions on one repo.
• Hooks — command hooks with Claude's stdin-JSON/stdout-decision contract and matcher semantics; see the capability matrix for compact lifecycle limits.
• CLAUDE.md, memory & rules — the ancestor hierarchy, recursive @import (the AGENTS.md bridge), auto memory, and .claude/rules/.
• Settings & permissions — settings.json precedence and merge semantics, with deny rules as a hard block.
• MCP servers — native, project-configured, and standalone managed stdio or selected remote HTTP/SSE servers expose tools, prompts, and resources behind central policy admission and source-specific controls; see the capability matrix for exact limits.
• Compaction resilience — proactive checkpointing on supported model transports, with instruction preservation and bounded recovery; see the user guide.
• Plugins — explicit local marketplace and plugin lifecycle management, immutable admission, inventory, recovery, and session reload; see Installed plugins.
• Images & notebooks — Read delivers image files and cell-aware .ipynb output (plots included) as real image blocks on a vision-capable model, degrading to a text placeholder on a non-vision model; notebooks can be edited cell-by-cell with NotebookEdit; a genuinely unsupported binary (e.g. a PDF) returns a clean binary error.
• Git commits — nudges richer, repo-style-matching commit messages by default.

Everything unrecognized degrades safely instead of crashing (the completeness floor). The full, always-current compatibility matrix is in doc/supported-features.md.

Control surface

Inside a session: /skills lists loaded skills; /agents lists the subagent catalog permitted by the current main-agent policy; /doctor gives an explicit project compatibility report; bare /mcp shows bounded passive status, while TUI-only /mcp manage opens interactive administration; /usage reports a per-subagent token/cost breakdown; /quota reports provider quota headers; alt+a opens the subagent status panel. Outside a session, picc mcp provides scoped MCP inventory and configuration commands. Eligible user-invocable skills whose names do not conflict with built-ins appear in the / autocomplete menu. Model and per-model steering are configured outside the project — see the user guide.

Repository layout

Path	Contents
src/	The harness: loaders (claude/), engines (engine/), Pi runtime layer (runtime/), capability registry (registry/), extension entry (index.ts)
bin/picc.mjs	Launcher (Pi + extension preloaded)
examples/hello-claude	Minimal demo project
examples/full-surface	Larger fixture exercising a broad slice of the feature surface
test/	Unit, offline-integration, and live e2e tests (vitest) — see doc/testing.md
doc/	User guide, architecture, supported features, testing, and the pinned Pi contracts

Development

npm run typecheck:all    # strict TS over src + tests
npm test                 # unit lane (same as test:unit)
npm run test:integration # offline whole-extension integration lane
npm run test:e2e         # packaged, compiled real-Pi, and source-fallback witnesses
npm run test:all         # unit + integration + e2e
npm run gen:capabilities # regenerate doc/supported-features.md from the registry

Support claims are pinned to a Claude Code ~2.1.x (mid-2026) baseline in the capability registry (src/registry/capability-registry.ts); the runtime compatibility report is generated from it, so docs and behavior cannot drift. See CONTRIBUTING.md.

License

MIT