pi

name	pi
description	Provides Pi-specific guidance for extensions, skills, `.pi/` config, `settings.json`, `models.json`, packages, providers, themes, SDK/RPC, sessions, and compaction in Pi, the coding agent. Use when the user mentions Pi or Pi-specific terms such as `.pi/`, `SKILL.md`, `createAgentSession()`, `thinkingLevel`, `session_before_compact`, `pi-ai`, `pi-tui`, `pi-agent-core`, or `pi-coding-agent`. Not for Raspberry Pi hardware, the math constant, or unrelated generic tooling.
license	GPLv3
compatibility	Pi-specific guidance for agents that support Agent Skills

Pi Coding Agent

Pi is a minimal terminal coding harness. Default tools: read, write, edit, bash, grep, find, ls. Modes: interactive (pi), print (pi -p), JSON (--mode json), RPC (--mode rpc), or embedded (createAgentSession()). Sub-agents, plan mode, permission flows, and MCP are intentionally left to extensions and Pi packages.

Pi's philosophy: adapt Pi to your workflows, not the other way around.

Architecture

Core packages on npm (source: github.com/earendil-works/pi):

Package	Purpose
@earendil-works/pi-ai	Unified LLM API across 20+ providers
@earendil-works/pi-agent-core	Agent runtime with tool execution and state
@earendil-works/pi-tui	Terminal UI components
@earendil-works/pi-coding-agent	CLI, extensions, skills, sessions, settings
@earendil-works/pi-web-ui	Web components for chat interfaces

File System Layout

~/.pi/agent/                    # Global config dir (PI_CODING_AGENT_DIR overrides)
├── settings.json               # Global settings
├── auth.json                   # Credentials (0600 perms)
├── models.json                 # Custom provider/model definitions
├── keybindings.json            # Keyboard shortcuts
├── extensions/                 # Auto-discovered
├── skills/                     # Auto-discovered
├── prompts/                    # Auto-discovered
├── themes/                     # Custom themes
└── sessions/                   # JSONL session files

<project>/
└── .pi/                        # Project-local config (overrides global)
    ├── settings.json
    ├── extensions/
    ├── skills/
    ├── prompts/
    ├── themes/
    └── agents/                 # Agent definitions (subagent extension)

Key Concepts

• Extensions — TypeScript modules with full system access. Hook into Pi's lifecycle to register tools, intercept calls, add commands, build UI. → references/extensions.md
• Skills — Markdown capability packages (SKILL.md + frontmatter) following the Agent Skills standard. Pi loads names + descriptions into the system prompt; bodies load on demand. → references/skills.md
• Settings — Hierarchical JSON: project .pi/settings.json merges over global ~/.pi/agent/settings.json. → references/settings.md
• Packages — Bundles of extensions/skills/prompts/themes via npm, git, or local paths. Installed with pi install. → references/packages.md
• Project trust — Pi 0.79+ asks before loading project-local settings, resources, and packages; decisions persist in ~/.pi/agent/trust.json. --approve/--no-approve override per run; defaultProjectTrust sets the non-interactive fallback. → references/settings.md
• Context files & prompt templates — Pi loads AGENTS.md / CLAUDE.md from the agent dir and from cwd up through ancestors. .pi/SYSTEM.md replaces the system prompt; APPEND_SYSTEM.md appends. Prompt templates in prompts/ become slash commands. → references/settings.md
• SDK — Programmatic embedding via createAgentSession(); createAgentSessionRuntime() for session replacement. → references/sdk.md
• Custom providers & models — models.json or extension pi.registerProvider() for any OpenAI-/Anthropic-/Google-compatible or custom LLM endpoint. → references/providers.md
• Sessions & compaction — Append-only JSONL with a tree structure; branch with /tree, /fork, /clone, compact with /compact. Auto-compaction triggers when contextTokens > contextWindow - reserveTokens. Extensions intercept via session_before_compact. → references/extensions.md and references/sdk.md

How to Use This Skill

Task	Reference
Writing an extension (tools, commands, events, UI)	references/extensions.md
Creating a skill	references/skills.md
Configuring Pi (settings, env vars, CLI flags)	references/settings.md
Building a shareable package	references/packages.md
Embedding Pi programmatically	references/sdk.md
Adding LLM providers or models	references/providers.md
Looking for a recipe or pattern	references/patterns.md

For exact CLI flags run pi --help or read the relevant reference. Resource flags (--no-extensions, --no-skills, --no-context-files, --no-builtin-tools, etc.) are documented in references/settings.md.