pi-code

Claude Code experience for the pi coding agent, in one package. Point pi at a project that already has a .claude/ directory and it reads your existing config: rules, commands, skills, hooks, output styles, MCP servers, and agents. It also adds the Claude Code features pi lacks: a todo overlay, checkpoints, memory, web search, and subagents.

What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes.

Install

pi install npm:pi-code       # from npm
pi install -l npm:pi-code    # project-local instead, writes .pi/settings.json

Other sources:

pi install git:github.com/ilovepixelart/pi-code
pi install ./pi-code         # local checkout, then /reload after edits

One pi install and everything below loads on the next start. pi list shows what is installed, pi config toggles individual resources, and pi update pi-code upgrades it. Each feature is an extension under extensions/.

What it does

| Feature | Reads / provides | Extension | |---|---|---| | Global + project rules | ~/.claude/rules, .claude/rules (nearest at or above cwd); unscoped rules inlined in full, paths:-scoped rules surfaced as pointers and auto-attached (the rule body is appended to a read/edit/write result when a matching file is touched, once per rule per session) | claude-rules.ts | | Custom slash commands | .claude/commands/**/*.md (namespaced /dir:name); $ARGUMENTS (with the ARGUMENTS: append when unused), 0-based $ARGUMENTS[N]/$N, named arguments: frontmatter, ${CLAUDE_SESSION_ID}/${CLAUDE_EFFORT}/${CLAUDE_SKILL_DIR}/${CLAUDE_PROJECT_DIR} (in bodies and allowed-tools rules); !`cmd` and multi-line ```! bash (whitespace-bounded, merged stderr, 2-minute budget, a failure aborts the invocation with the documented exit-1 carveout), @file inlining; allowed-tools with Bash(...) and Read/Edit/Write path scopes enforced at call time (gitignore anchors, Edit governs writes), disallowed-tools, argument-hint, model (switches the session model for the command's turn, restored after), shell: powershell (runs the command's injected spans through PowerShell when a pwsh binary is present, else falls back to /bin/sh); disable-model-invocation is parsed but not applied; project commands gated on approval | commands.ts | | /init | generates a project context file: detects an existing AGENTS.md/CLAUDE.md (proposes improvements) or none (creates AGENTS.md, pi's preferred name), ingesting .cursor/rules, .cursorrules, and .github/copilot-instructions.md when present; drives the main agent with full tools via a prompt (not a tool-less completion) so it analyzes the codebase and writes the file itself | init.ts | | Skills | .claude/skills → pi skill discovery, project skills gated on approval (pi reads name, description, disable-model-invocation; allowed-tools is inert in pi's loader) | skills.ts | | Hooks | .claude/settings.json hooks: PreToolUse (blocks, rewrites input via updatedInput), PostToolUse (feedback and additionalContext land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd, Notification (idle_prompt, the type pi can source), InstructionsLoaded (observational: fires per loaded context file at session start, plus path_glob_match on a scoped-rule attach and include per resolved @import; deduped per session; nested_traversal/compact reasons never fire since pi does not lazily load nested CLAUDE.md or reload after compaction); type: http entries POST the payload (a 2xx JSON body renders the decision, everything else is non-blocking per Claude's contract), type: prompt evaluates in-process against the session model, type: mcp_tool calls a connected server's tool, and type: agent (experimental) spawns a read-only Read/Grep/Glob subagent that returns the JSON decision (a missing model/server/runner is non-blocking, only a PreToolUse timeout fails closed); Claude matcher semantics incl. mcp__server__tool names; payloads carry session_id, transcript_path, cwd, permission_mode, effort; permissionDecision: "ask" prompts via a confirm dialog (blocks when headless), SubagentStop/PostToolUseFailure are notify-only, and a timed-out PreToolUse/UserPromptSubmit hook fails closed at a 60s default (Claude: 600s, non-blocking) since pi has no permission backstop | hooks.ts | | Output styles | .claude/output-styles + active outputStyle; plus styles shipped by enabled plugins (manifest outputStyles, default output-styles/, ranked below the user's and project's own); Claude replace semantics with keep-coding-instructions; bundled Explanatory/Learning/Proactive; /output-style [name] | output-styles.ts | | CLAUDE.md @imports and rewriting | resolves @path imports pi's native loader skips (4-hop depth, budget-capped); loads every CLAUDE.local.md from the repo root down to cwd (approval-gated, root first); injects managed claudeMd from managed-settings.json at the top of context; honors claudeMdExcludes (glob/absolute-path skip list from user, approved-project, and managed settings, merged; managed content never excluded); strips block-level HTML comments from CLAUDE.md, rule, and imported bodies (fenced-code comments preserved), so a commented-out @import does not expand; with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set, loads CLAUDE.md/.claude/CLAUDE.md/.claude/rules/*.md/CLAUDE.local.md from each --add-dir directory (comma-separated for several, since pi's flag is single-value) | context-imports.ts | | MCP servers | user ~/.claude.json (incl. per-project projects[cwd] local scope), ~/.pi/agent/mcp.json; project .mcp.json, .pi/mcp.json (once approved; enabledMcpjsonServers/disabledMcpjsonServers/enableAllProjectMcpServers honored, consent keys only from non-repo settings); stdio/HTTP/SSE/WebSocket by type (WebSocket is url-only: any headers/bearerToken/headersHelper on a ws server is ignored with a warning); ${VAR:-default} expansion; a headersHelper command whose stdout JSON merges into the transport headers (http/sse); managed allowedMcpServers/deniedMcpServers read from managed-settings.json only ({serverName} entries, applied globally across scopes, allow list exclusive with an empty array = lockdown, deny wins); MCP_TIMEOUT/MCP_TOOL_TIMEOUT; tools refresh on list_changed; bearer tokens, or OAuth for remote servers (browser login on 401 after a confirm, tokens under ~/.pi/agent/mcp-oauth, silent refresh later) | mcp.ts | | Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles, commands, skills) that pi would otherwise trust silently | internal/project-approval.ts | | Subagents / Task | builtin Explore/Plan/general-purpose agents, ~/.claude/agents and ~/.pi/agent/agents, plus project .claude/agents and .pi/agents (scanned recursively into subfolders) merged by default once the project is trusted (project wins on a name clash); frontmatter tools/disallowedTools/model (sonnet/opus/haiku/fable tier aliases or a concrete id)/effort/skills preload/permissionMode: plan/maxTurns/memory (user/project/local give the child its own persistent store under .claude/agent-memory[-local], injected with Read/Write/Edit enabled, gated on auto memory; the parent conversation's memory is never loaded into a subagent, matching Claude); parallel and chain modes (pi extensions), one nesting level; background runs with cancel and resume | subagent/ | | Plan mode | plan_mode_complete tool, tool snapshot/restore that survives /reload | plan-mode/ | | Todo list | persistent overlay, status machine, compaction-safe | todo.ts | | Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later; 100 per session, repos pruned after 30 days | git-checkpoint.ts | | Persistent memory | per-repo memories under ~/.pi/agent/memory keyed on the repository root (subdirectory sessions share one store, as Claude does; pi's own store, separate from Claude's), index injected each session within Claude's 200-line/25KB bound (YAML frontmatter and block HTML comments stripped before it counts or loads); a save that would overflow it reports why; a memory written with frontmatter gets a modified: ISO timestamp; honors autoMemoryEnabled (settings) and CLAUDE_CODE_DISABLE_AUTO_MEMORY (env) to turn it off, and autoMemoryDirectory (absolute or ~/) to relocate the store | memory.ts | | WebSearch / WebFetch | key-free DuckDuckGo search (with allowed_domains/blocked_domains); SSRF-guarded fetch that prefers markdown via Accept then converts HTML, with Claude's 15-minute per-URL cache and an optional prompt that runs the page through the model in-process and returns the answer (falls back to markdown when headless or on error) | web.ts | | AskUserQuestion | 1-4 questions per call (asked in sequence), each with header and 2-4 options, single- or multiSelect, plus free-text | question.ts | | Statusline | Claude statusLine command contract (stdin JSON incl. version, hook_event_name, session_name, cost durations and line counters, context percentages; padding, refreshInterval, 300ms debounce); built-in turn state + session cost fallback | status-line.ts | | Notifications | terminal notification when a turn ends (OSC 777 / Kitty OSC 99 / Windows toast); honors preferredNotifChannel (terminal_bell, notifications_disabled, iterm2_with_bell, else desktop) from user settings; fires only when you "appear to be away" (approximated by turn duration, since pi exposes no terminal-focus signal) | notify.ts | | Claude plugins | installed marketplace plugins (~/.claude/plugins/cache), active per enabledPlugins in user settings only (a checked-out repo cannot flip which code-bearing plugins run, so project settings never toggle them): commands as /plugin:name, agents, hooks and MCP servers (tools aliased mcp__plugin_<plugin>_<server>__<tool>) and output styles with ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA} and ${user_config.KEY} (from pluginConfigs[id].options in user settings) substituted; skill dirs contribute too, though pi's loader names them without the plugin prefix | internal/plugins.ts |

pi has no general permission system, so