Pi Dev Rules Agent Skill

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

| File | Covers |

| ------ | -------- |

| references/cli-and-usage.md | Install, auth, launching, how Pi works (agent loop, context assembly, session tree), the full CLI reference (commands, flags, modes), slash commands, message queue, context files, environment variables (incl. bash-tool PI_SESSION_*/PI_MODEL), sessions, keybindings |

| references/providers-and-models.md | Subscription & API-key providers (30+), llama.cpp local router, NVIDIA RTX recipe presets, auth.json (+ scoped env), cloud providers (Azure/Bedrock/Vertex/Cloudflare), custom models in models.json, the generated field reference for every provider, model and compat key, custom-provider extensions |

| references/settings-and-compaction.md | Configuration layout (agent directory vs project .pi/, context files), settings.json schema + example, trust/analytics/retry/transport keys, compaction (auto/manual) and branch summarization |

| references/extending-pi.md | Extension API (events, tools, commands, UI), tool parameter validation with @earendil-works/pi-schema and the TypeBox features it ignores, Skills (SKILL.md), Prompt Templates, Themes, Packages, virtual models (pi.registerVirtualModel) |

| references/mcp.md | Built-in MCP support (2026-09-29): mcp.json global and project servers, stdio vs streamable HTTP, pi mcp add/remove/list, OAuth sign-in, exposure modes (codemode, codemode-deferred, deferred, direct, hidden) with toolExposure, codemode/tool_search tools, resources, permissions, servers from extensions, SDK wiring, and the --no-mcp / mcp__* tool patterns |

| references/codemode.md | The codemode tool: script input and the // @options: line, globals (tools.<name>(), text(), image(), console.log(), store()/load(), searchTools(), describeTool()), what tool calls resolve to, classifier and image models, namespaces and the inline budget, limits |

| references/tui-components.md | TUI component system for custom extension/tool UIs (components, overlays, theming, custom editor) |

| references/security-and-containerization.md | Project-trust model (trust.json, defaultProjectTrust), no built-in sandbox, Gondolin micro-VM, Docker, OpenShell, Docker Sandboxes |

| references/session-format.md | Session JSONL schema: versions, content blocks, entry types, tree/context building, SessionManager API, plus the model-facing message types |

| references/programmatic.md | SDK, CLI integration (interactive/print/JSON/RPC mode choice, RpcClient, fork-and-rebrand), JSON event-stream mode, RPC protocol, RPC command reference, RPC extension UI |

| references/platform-setup.md | Windows, Termux, tmux, per-terminal modified-Enter setup, shell aliases |

| references/development.md | Monorepo package list, build-from-source and standalone-binary builds, supply-chain rules, AGENTS.md development rules, the CONTRIBUTING.md gate |

| references/philosophy-and-design.md | Creator Mario Zechner's design manifesto (blog, 2025-11-30; manually curated, not auto-built): minimal prompt <1000 tokens, 4 tools, YOLO by default, the non-features it lists (MCP/plan mode/to-dos/sub-agents/background bash) with their intended alternatives and the MCP entry annotated as superseded since 2026-09-29, multi-provider architecture, Terminal-Bench 2.0 results |

| references/chord.md | @earendil-works/chord: the typed host runtime (contracts, declarations, registries, principals, handles, hot reload), hosts and links (memoryLinkPair, ipcLink, webSocketLink), and chord/delta replicated latest-value state with the fold-while-watching watches. Built from packages/chord/{README.md,docs/{guide,spec,tutorial}.md,src/delta/README.md}; Pi Durable uses Chord, but the Pi coding agent does not; the spec describes the 1.x runtime, now schema-checked with @earendil-works/pi-schema. A second-generation runtime (v2) lives in packages/chord/src/next with its design in packages/chord/docs/next and an experimental @earendil-works/chord/next export; it is not bundled here |

| references/durable.md | Pi Durable overview, curated from the 2026-10-01 Earendil blog post and the v1.5.0 tree: the harness/conversation/agent/task/execution-environment vocabulary, the positioning (a harness for building agentic applications, not the Pi CLI), the version timeline (1.0.0 with Pi 1.0 → 1.5.0, lockstep versions, breaking changes), install and code shape, the package layout and its 38 runnable examples, and the blog demos deleted in 1.2.0. Start here for status and routing |

| references/agent-harness.md | Internal runtime packages: @earendil-works/pi-durable (durable conversation/task/document harness, experimental API, stored before shown), @earendil-works/pi-agent-core (tool calling and state), @earendil-works/pi-telemetry (vendor-neutral telemetry contracts, adapters, typed schemas). Built from the three package READMEs; not user docs, and durable.md is the entry point |

| references/durable-spec.md | The normative Pico5 specification behind pi-durable (6531 lines): records and lifetimes, documents and mutation ownership, tasks and the effect sandwich, submissions and inbox, extensions/hooks/tools, telemetry. A design document for an experimental package, not a frozen API; the bundled text is the v1.5.0 spec |

| references/changelog.md | Release history: the last 25 versions with their headline change, extracted from packages/coding-agent/CHANGELOG.md (291 release sections; read the file in the checkout for the full text) |

Pi 1.4.0 and 1.5.0 update notes

• Every models.json field now has a generated reference (docs/models-configuration.md), bundled

in providers-and-models.md.

• Tool arguments are validated as JSON Schema by @earendil-works/pi-schema; TypeBox schemas still

work, but Type.Refine, Type.BigInt, Type.Undefined, codecs and Format.Set formats do not

apply to them, and plain JSON Schema tools get the same coercion.

• Extensions can show a changelog after an update (pi.changelogPath or the package's

CHANGELOG.md; collapseChangelog condenses it).

• pi update accepts a custom command: PI_SELF_UPDATE_COMMAND or the selfUpdateCommand setting,

with {packageName}, {version} and {installSpec} filled in.

• Streaming got cheaper: large tool calls parse incrementally and rendered rows are reused. Rex is

a supported terminal (OSC 8, truecolor, inline images).

• New default OpenAI model gpt-6.1-sol (also after ChatGPT sign-in); GPT-6.1 Terra is available

through OpenAI, Azure and Codex; the catalog moved to models.dev v2.

• Codemode models.classify() accepts images; scripts wait up to 60 s for a free worker and

PI_CODEMODE_MAX_WORKERS raises the two-worker limit.

• Compaction and branch summaries use the model's output limit, so reserveTokens no longer caps

them; it only decides when compaction starts.

• MCP OAuth uses pi's Client ID Metadata Document by default (oauth.clientRegistration: "auto");

"dcr" always registers dynamically, and pi mcp add --oauth-client-registration selects it.

• A saved "Do not trust" decision now wins over auto-trust for projects whose only resource is

AGENTS.md.

• Chord, Durable and the built-in tools build schemas with pi-schema. Durable 1.5.0 replaces the

documentState/viewState/watchEvents surface with windowed conversation views and Chord

watches, and Storage.commit() stores a group of commits; chord exports the experimental v2

runtime as @earendil-works/chord/next.

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.

• Tool parameters are any JSON Schema; Pi validates them with @earendil-works/pi-schema.

TypeBox schemas are JSON Schema and still work, but refinements, BigInt, Undefined, codecs and

Format.Set formats do not apply to tool arguments (check those in execute()), and plain JSON

Schema tools, including MCP tools, get the same coercion as TypeBox tools.

• 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.5.0 on 2026-11-02).

Versions follow the monorepo, and earlier releases include breaking changes. The Pico5 spec is

a design document. Quote the source tree state (pi@f9a263655), 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–37) 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.