skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
agents365-ai/365-skills240 installs

pi-dev-rules

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.

How do I install this agent skill?

npx skills add https://github.com/agents365-ai/365-skills --skill pi-dev-rules
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is a comprehensive technical reference for the Pi coding agent, providing instructions on installation, configuration, and extensibility. Analysis confirms that all referenced installation scripts and external links point to the official product domains and repositories (pi.dev and Earendil Works), consistent with the skill's purpose. No malicious patterns or security risks were identified.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

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

FileCovers
references/cli-and-usage.mdInstall, 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.mdSubscription & 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.mdConfiguration 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.mdExtension 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.mdBuilt-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.mdThe 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.mdTUI component system for custom extension/tool UIs (components, overlays, theming, custom editor)
references/security-and-containerization.mdProject-trust model (trust.json, defaultProjectTrust), no built-in sandbox, Gondolin micro-VM, Docker, OpenShell, Docker Sandboxes
references/session-format.mdSession JSONL schema: versions, content blocks, entry types, tree/context building, SessionManager API, plus the model-facing message types
references/programmatic.mdSDK, 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.mdWindows, Termux, tmux, per-terminal modified-Enter setup, shell aliases
references/development.mdMonorepo package list, build-from-source and standalone-binary builds, supply-chain rules, AGENTS.md development rules, the CONTRIBUTING.md gate
references/philosophy-and-design.mdCreator 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.mdPi 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.mdInternal 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.mdThe 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.mdRelease 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.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/agents365-ai/365-skills/pi-dev-rules">View pi-dev-rules on skillZs</a>