v0.8.0 to v0.9.0

20 added, 11 removed. Audit B to B.

---

name: pi-dev-rules

- version: 0.8.0

+ version: 0.9.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, codemode, 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.2.0","fetched":"2026-10-13","piRevision":"06a466935","version":"0.8.0"}

+ metadata: {"source":"https://pi.dev/docs/latest","docVersion":"1.3.0","fetched":"2026-10-16","piRevision":"71023aec1","version":"0.9.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. 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, `auth.json` (+ scoped `env`), cloud providers (Azure/Bedrock/Vertex/Cloudflare), custom models in `models.json`, `compat`, custom-provider extensions |

+ | `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`, `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, 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. Built from `packages/chord/{README.md,docs/{guide,spec,tutorial}.md,src/delta/README.md}`; no Pi package depends on chord since 1.2.0, and the spec describes the runtime rather than a promoted API |

- | `references/durable.md` | **Pi Durable** overview, curated from the 2026-10-01 Earendil blog post and the v1.2.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.2.0, lockstep versions, breaking changes), install and code shape, the package layout and its 32 runnable examples, and the blog demos deleted in 1.2.0. Start here for status and routing |

+ | `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. 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 current runtime |

+ | `references/durable.md` | **Pi Durable** overview, curated from the 2026-10-01 Earendil blog post and the v1.3.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.3.0, lockstep versions, breaking changes), install and code shape, the package layout and its 32 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` (5340 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.2.0 spec |

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

+ | `references/durable-spec.md` | The normative **Pico5 specification** behind `pi-durable` (5352 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.3.0 spec |

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

+ ## 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):

```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 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 published but application-neutral and no Pi package depends on it;

- `pi-durable` is experimental (1.0.0 on 2026-10-01 with Pi 1.0, 1.2.0 on 2026-10-12, versioned in

- lockstep with the monorepo, breaking changes in every release) and the Pico5 spec is a design

- document. Quote them as the current source tree state (pi@`06a466935`), not as promised API.

+ 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.