Pi Dev Rules

Pi is a minimal terminal coding harness: lightweight core, extended through TypeScript customizations. Package: @earendil-works/pi-coding-agent. Maintained by Earendil Inc. (MIT). This skill mirrors the official docs at https://pi.dev/docs/latest so you can answer Pi questions and build Pi customizations without re-fetching. Five further bundles describe material the pi.dev docs site does not hold: the internal monorepo architecture (the Chord typed host runtime, the durable agent harness with its Pico5 specification, the agent core, telemetry), a Pi Durable overview curated from the 2026-10-01 Earendil blog post (what the experimental harness is, its version timeline, and which blog demos were removed in 1.2.0), and the repository's own development/contribution rules.

When to use this skill

• Installing, authenticating, or launching Pi; explaining CLI flags / slash commands.
• Configuring providers, API keys, custom models (models.json), or proxies.
• Editing settings.json, keybindings, themes; understanding sessions & compaction.
• Understanding the project-trust security model and running Pi in containers/sandboxes.
• Extending Pi: writing extensions, skills, prompt templates, packages, custom providers, TUI UI; enabling codemode or writing its scripts.
• Checking Pi's version history / what changed in a recent release.
• Driving Pi programmatically via the SDK, RPC mode, or JSON event-stream mode.
• Setting up Pi on Windows/Termux/tmux/specific terminals, or building it from source.
• Understanding why Pi is designed the way it is: the creator's philosophy (minimal core, 4 tools, YOLO by default; the 2025-11-30 manifesto lists MCP, plan mode, to-dos, and sub-agents as deliberate non-features, and built-in MCP landed later, on 2026-09-29) and how to configure or extend Pi along those lines instead of against them.
• Working inside the pi monorepo: the @earendil-works/chord typed host runtime (contracts, hosts and links, hot reload, delta/replicated state), the durable harness (@earendil-works/pi-durable, Pico5), the agent core, and telemetry. The experimental server/client/protocol packages were removed in 1.2.0.
• Building on or asking about Pi Durable (@earendil-works/pi-durable): what the harness is, which version shipped what, where the runnable examples live, or why a blog-post demo path no longer exists.

Reference index: load the file you need

Pi 1.3.0 update notes

• sessionShareDestination selects auto, gist, or radius for /share.
• Resumed sessions restore active tools. --tools +name/-name adjusts that set.
• Ambiguous --model matches prefer a provider with credentials. Otherwise, specify --provider.
• Kimi Code now uses Chat Completions. Custom base URLs must include /v1.
• Codemode permits at most two live workers per Pi process, including cancelled workers until exit.
• Pi Durable supports SQLite table prefixes and shared Cloudflare adapter queues.

Starter plugins

Every Pi user should install these three (same author, battle-tested):

pi install npm:pi-subagents       # subagents / loop / chain / parallel
pi install npm:pi-lens            # real-time LSP diagnostics
pi install npm:pi-web-access      # web search, URL fetch, YouTube, PDF

Then pi list to verify, restart Pi. MCP needs no package: it is built in since 2026-09-29 (see references/mcp.md). An extension that registers /mcp, such as pi-mcp-adapter, replaces the built-in support instead of adding to it.

Cheat sheet

curl -fsSL https://pi.dev/install.sh | sh                         # install (pins dependencies)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent   # npm alternative (no pinned transitive deps)
export ANTHROPIC_API_KEY=sk-ant-...                               # or run /login in-session
cd /path/to/project && pi                                          # start interactive (may prompt to trust the project)

pi update                                 # update Pi itself (pi update self / pi update --self are aliases)
pi list                                   # list installed packages
pi -c                       # continue most recent session
pi -r                       # browse/resume sessions
pi --session <path|id>      # open specific session
pi --fork <path|id>         # fork a session
pi --no-session             # ephemeral (no save)
pi -a / -na                 # trust / don't trust project-local files for this run

pi -p "Summarize this codebase"                 # print mode (non-interactive)
pi @README.md "Summarize this"                  # attach files/images with @
cat file | pi -p "..."                          # pipe stdin
pi --provider openai --model gpt-4o "..."       # pick provider/model
pi --model sonnet:high "..."                    # model:thinkingLevel
pi --tools read,grep,find,ls -p "..."           # allowlist tools (-xt excludes; +name/-name adjusts defaults)
pi --mode json "..." | jq -c 'select(.type=="message_end")'   # JSON stream
pi --mode rpc                                   # JSON-RPC over stdin/stdout

# In-editor: @file (fuzzy), !cmd (run+send), !!cmd (run, hidden), /command, Ctrl+L model, Shift+Tab thinking, Ctrl+X copy
# While the agent runs: Enter queues a steering msg, Alt+Enter a follow-up, Esc aborts + restores

Key locations (global ~/.pi/agent/, project .pi/): settings.json, auth.json, models.json, keybindings.json, trust.json, AGENTS.md, SYSTEM.md, extensions/, skills/, prompts/, themes/, sessions/.

Hard rules

• Install package name is exactly @earendil-works/pi-coding-agent. The pi.dev installer (curl -fsSL https://pi.dev/install.sh | sh) pins dependencies and is the documented install path; a global npm install needs --ignore-scripts and pins nothing.
• Project context file is AGENTS.md (Pi also reads CLAUDE.md); put it in the project root.
• Extensions run with full system permissions: treat them as trusted code; gate dangerous ops (rm, sudo, sensitive paths) with ctx.ui.confirm or a tool_call block handler.
• Project trust is an input-loading guard, not a sandbox. Pi ships no built-in sandbox; a project is "trusted" only to decide whether to load its .pi/ resources (settings/extensions/skills/ prompts/themes); decisions live in ~/.pi/agent/trust.json, governed by defaultProjectTrust (ask/always/never), overridable per run with --approve/--no-approve. For untrusted repos or unattended runs, isolate with a container/VM (Gondolin/Docker/OpenShell); don't mount host ~/.pi/agent unless the sandbox should see host credentials.
• MCP is built in since 2026-09-29, configured in ~/.pi/agent/mcp.json or a project .pi/ mcp.json; the project file is read only after the project is trusted, because stdio servers run commands. MCP calls go through the tool pipeline, so tool_call handlers and permission gates apply (codemode calls carry parentToolCallId). Installing an extension that registers /mcp (pi-mcp-adapter) disables the built-in support; disable it deliberately with "extensions": ["-builtin:mcp"], pi config, or --no-mcp for one run.
• In extension/SDK tools: throw on error, never return an error flag. Pi wraps a thrown error into an error tool result (isError: true); the docs defer to ToolDefinition in packages/coding-agent/src/core/extensions/types.ts for the exact contract. Limit tool output to ~50KB / 2000 lines (DEFAULT_MAX_BYTES = 50 * 1024). Use StringEnum (from @earendil-works/pi-ai) for LLM-facing enums.
• Skill name: 1–64 chars, lowercase a-z 0-9 -, no leading/trailing or consecutive hyphens; description ≤1024 chars and must say when to load it (a skill with no description won't load).
• chord.md, durable.md, agent-harness.md, and durable-spec.md describe internals, not a stable contract. Chord is application-neutral and used by Pi Durable, not by the Pi CLI. pi-durable is experimental (1.0.0 on 2026-10-01 with Pi 1.0, 1.3.0 on 2026-10-15). Versions follow the monorepo, and earlier releases include breaking changes. The Pico5 spec is a design document. Quote the source tree state (pi@71023aec1), not a promised API.
• The Pi Durable blog post is a 2026-10-01 snapshot. Its "Try it" demos (packages/coding-agent/src/experimental/{durable,vacation}/) were deleted in 1.2.0 by commit 7472cda0d; the durable harness itself is unaffected. Run examples from packages/durable/test/examples/ (00–31) instead, and read durable.md for the version timeline.
• auth.json holds API keys and OAuth tokens: Pi writes it 0600, keep it private and out of version control. Credential priority: CLI --api-key → auth.json → env var → custom-provider keys in models.json.
• Project settings override agent-directory settings, and resource lists are combined rather than replaced (per-model objects such as compaction thresholds merge before the model lookup). Use pi install -l to write a package declaration to .pi/settings.json, which Pi reads only after the project is trusted.