pi-dev-rules · v0.6.0 · 2026-10-03 · sha256 542c58d8ecd383b2
pi-dev-rules v0.6.0B
Immutable. This exact content never changes and is served at /api/v1/blob/542c58d8ecd383b2.
---
name: pi-dev-rules
version: 0.6.0
description: "Authoritative reference for Pi (@earendil-works/pi-coding-agent): install, configure, run, and extend it. Use for the CLI and configuration, providers and models, extensions, skills, MCP, the SDK/RPC, security and trust, design philosophy, and the pi repository's internals and contribution rules."
license: MIT
metadata: {"source":"https://pi.dev/docs/latest","docVersion":"1.0.1","fetched":"2026-10-03","piRevision":"a7229ddc2","version":"0.6.0"}
---
# 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. Four further bundles describe material that has
no page on the website: the **internal monorepo architecture** (the Chord composition runtime, the
durable agent harness with its Pico5 specification, the agent core, telemetry) 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; 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` composition runtime (plugin
loading, service catalogue, RPC transport, delta/replicated state), the durable harness
(`@earendil-works/pi-durable`, Pico5), the agent core, telemetry, and the experimental
`server`/`client`/`protocol` packages.
## 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, `auth.json` (+ scoped `env`), cloud providers (Azure/Bedrock/Vertex/Cloudflare), custom models in `models.json`, `compat`, 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), 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 |
| `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`: plugin loading/composition/bundling, the service catalogue, RPC transport, `bundleFacetPackage` + facet bundle loaders, and `chord/delta` replicated latest-value state. Built from `packages/chord/{README.md,PLANNING.md,src/delta/README.md}`; `PLANNING.md` is a plan, not a frozen API |
| `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 |
| `references/durable-spec.md` | The normative **Pico5 specification** behind `pi-durable` (4610 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 |
| `references/changelog.md` | Release history: the last 25 versions with their headline change, extracted from `packages/coding-agent/CHANGELOG.md` (283 release sections; read the file in the checkout for the full text) |
## Starter plugins
Every Pi user should install these three (same author, battle-tested):
```bash
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
```bash
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 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`. The pi.dev installer
(`curl -fsSL https://pi.dev/install.sh | sh`) pins dependencies and is the recommended path since
1.0.1; 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"]` or `pi config`.
- **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`, `agent-harness.md`, and `durable-spec.md` describe internals, not a stable
contract.** Chord is published but application-neutral, `pi-durable` is experimental and its API
changes between releases, the Pico5 spec is a design document, and
`PLANNING.md`/`server`/`client`/`protocol` are explicitly experimental. Quote them as the
current source tree state (pi@`a7229ddc2`), 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.