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. Three further bundles describe material that has no page on the website: the internal monorepo architecture (Chord runtime, agent harness) and the repository's own development/contribution rules. They are built from the pi source tree.

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.
• 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, no MCP/plan mode/to-dos/sub-agents) and how to configure/extend Pi along those lines instead of against them.
• Working inside the pi monorepo: the @earendil-works/chord runtime (plugin loading, service catalogue, RPC transport, delta/replicated state), the agent harness, facets/services, and the experimental server/client/protocol packages.

Reference index: load the file you need

Starter plugins

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

pi install npm:pi-mcp-adapter     # MCP server integration
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.

Cheat sheet

npm install -g --ignore-scripts @earendil-works/pi-coding-agent   # install (or: curl -fsSL https://pi.dev/install.sh | sh)
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 to exclude)
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 with --ignore-scripts.
• 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.
• 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 and agent-harness.md describe internals, not a stable contract. Chord is published but application-neutral, the harness docs are implementation specifications, and PLANNING.md/server/client/protocol are explicitly experimental. Quote them as the current source tree state (pi@2c2cd63), not as promised API.
• 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.