A Minimal Guide to Pi Agent

1. Start with the Right Mental Model

Pi is a minimal terminal coding harness.

Its core design principle: keep the core minimal and let you extend the workflow yourself (README.md > Philosophy).

The official docs state clearly which built-in features it does not provide, and the alternatives:

What this means: don't wait for Pi to give you a workflow. Turn the workflow you want into a skill / prompt / extension / package yourself.

By default the model gets only 4 tools: read, write, edit, bash. The read-only grep, find, and ls must be enabled explicitly (docs/quickstart.md, docs/usage.md).

2. The 6 Most Frequent Daily Actions

Source: README.md > Interactive Mode, docs/quickstart.md

One-off tasks (without the interactive UI):

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"   # stdin is merged into the initial prompt
pi -p @screenshot.png "What's in this image?"

3. Models and Thinking Levels: Switch by Task Difficulty

Source: README.md, docs/settings.md

• Use /model or Ctrl+L to switch models; press Ctrl+S in the picker to save the current model as the startup default.
• Use /thinking to switch thinking levels; Ctrl+S saves the default here too. Shift+Tab cycles quickly.
• Levels: off / minimal / low / medium / high / xhigh / max.
• Ctrl+P / Shift+Ctrl+P cycles through "scoped models" (configured via /scoped-models or --models).

Set them once from the command line:

pi --model sonnet:high "Solve this complex problem"   # provider/id + :thinking shorthand
pi --thinking high "Solve this complex problem"
pi --models "claude-*,gpt-4o"                          # limit which models can be cycled

A practical token-saving tip: use a low thinking level + a cheap model for simple changes, and switch to high only for complex refactors. For review tasks that read a lot and write little, enable read-only mode:

pi --tools read,grep,find,ls -p "Review the code"   # read-only: physically cannot modify files

4. Make It "Understand Your Project": AGENTS.md Has the Best ROI

Source: README.md > Context Files, docs/quickstart.md

On startup, Pi automatically loads and concatenates these files:

1. ~/.pi/agent/AGENTS.md (global)
2. AGENTS.md or CLAUDE.md in each parent directory walking up from cwd
3. AGENTS.md or CLAUDE.md in the current directory

If a directory has AGENTS.override.md, only that file is loaded for the directory, and AGENTS.md/CLAUDE.md are ignored.

What to write: project conventions, common commands, safety red lines, preferences.

# Project Instructions
- After changing code, run `npm run check`
- Never run production migrations locally
- Keep replies concise

Key points:

• After editing a context file, you must restart pi or run /reload for it to take effect.
• To fully replace the system prompt: .pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global); to only append, use APPEND_SYSTEM.md.
• Temporarily disable loading: --no-context-files / -nc.

5. Context Costs Money: Sessions / Branches / Compaction

Source: docs/sessions.md, docs/compaction.md

Session Management

• Sessions are saved automatically to ~/.pi/agent/sessions/, organized by working directory, as a JSONL tree.
• pi -c continues the latest session; pi -r lets you browse and pick; pi --no-session runs without saving; pi --name "xxx" names it (easier to find later in /resume).
• /new starts a new session, /session shows current session info (file, ID, tokens, cost), and /resume picks from history.

Branches: Don't Start Over Just Because the Chat Went Off Track

• /tree: jump back to any earlier node in the same file and continue (tree structure, all history kept). Picking a user message puts it back in the editor so you can edit and resend it, creating a new branch; picking a non-user entry continues directly from there.
• /fork: start a new session file from an earlier user message.
• /clone: copy the current branch into a new session file.
• When you switch away from a branch with /tree, Pi can summarize the abandoned branch and inject it at the new position to preserve context.

In one sentence: to compare several approaches in place → /tree; to get a separate file → /fork / /clone.

Compaction (Automatic Compression)

• Trigger: contextTokens > contextWindow - reserveTokens (default reserve is 16384).
• The most recent keepRecentTokens (default 20000) are kept uncompressed; older content is summarized by the LLM.
• Manual: /compact or /compact <custom instructions>.
• Important: compaction is lossy. The full history is still in the JSONL and you can go back with /tree, but summarized-away details won't automatically return to the context.

// ~/.pi/agent/settings.json or .pi/settings.json
{ "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 20000 } }

Switching Computers / Sharing

• /export [file] exports HTML or JSONL; /import <file> imports and continues.
• /share uploads it as a private GitHub gist and gives you a shareable HTML link.

6. Lock In Repetitive Work (The Key to Building Efficiently)

Source: docs/prompt-templates.md, docs/skills.md, README.md > Pi Packages

6.1 Prompt Templates: Reusable Prompts

Put them in ~/.pi/agent/prompts/*.md or .pi/prompts/*.md, and type /filename to expand.

<!-- ~/.pi/agent/prompts/review.md -->
---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes (`git diff --cached`). Focus on: ${1:-bugs, security, error handling}

Supports $1, $@, $ARGUMENTS, ${1:-default}, and ${@:N:L} slices.

6.2 Skills: On-Demand Capability Packs (Progressive Disclosure)

How it works: at startup only each skill's name + description goes into the system prompt; when a task matches, the model uses read to load the full SKILL.md. So when writing a skill, the description decides whether it gets triggered.

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
---
name: my-skill
description: Explain specifically what it does and when it should be used. Be specific.
---

# My Skill
## Steps
1. ...

• Locations: ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, .agents/skills/, or inside a package.
• Force a call: /skill:name, optionally with arguments: /skill:pdf-tools extract.
• You can reuse skills from other harnesses (just add them to settings):

{ "skills": ["~/.claude/skills", "~/.codex/skills"] }

6.3 Pi Packages: Bundle All of the Above to Share / Reuse

pi install npm:@foo/pi-tools        # also supports git:github.com/user/repo, https://..., ssh://...
pi install npm:@foo/pi-tools@1.2.3  # pin a version
pi list
pi update --extensions              # update packages only
pi update --all                     # update pi + all packages
pi config                           # interactively enable/disable resources in packages

-l installs locally to the project (.pi/). You can enable only some resources from a package (the object form of packages; see docs/settings.md).

Security reminder (from the official docs): Pi packages have full system access, extensions run arbitrary code, and skills can instruct the model to do anything. Read the source before installing third-party packages.

7. Don't Interrupt It: The Message Queue

Source: README.md > Message Queue

You can keep typing while the agent is working:

steeringMode / followUpMode can be set to "one-at-a-time" (default, waits for a reply) or "all" (sends together).

8. Non-Interactive & Scripted: Put pi in Your Pipeline

Source: README.md > Programmatic Usage, docs/usage.md

When the bash tool runs, commands receive these environment variables so scripts can look up context (README.md > Environment Variables):

PI_SESSION_ID, PI_SESSION_FILE, PI_PROVIDER, PI_MODEL, PI_REASONING_LEVEL; the CLI/RPC entry points also set AI_AGENT=pi and PI_CODING_AGENT=true so child processes can detect it.

9. Security and Trust Boundaries (Don't Skip This)

Source: README.md, docs/usage.md > Project Trust, docs/security.md

• No permission prompts: this is a design choice. By default it can modify files and run any command in your cwd.
• Use git or another checkpoint mechanism as your rollback safety net.
• Project Trust: when a project directory contains project-level settings / resources / .agents/skills and there's no saved decision, interactive mode first asks whether you trust it. Only after you trust it are .pi/settings.json, .pi resources, and project extensions loaded.
  • Non-interactive modes (-p, --mode json/rpc) don't prompt; they follow defaultProjectTrust: ask (default) / never ignore these project resources, always trusts them.
  • One-time override: -a / --approve, or -na / --no-approve.
  • /trust writes to ~/.pi/agent/trust.json (the current session doesn't reload; restart required).
• For risky scenarios: run it in a container, or implement your own confirmation flow with extensions; for background tasks, use tmux.
• Privacy switches: PI_OFFLINE=1 / --offline turns off all startup network requests; PI_SKIP_VERSION_CHECK=1 turns off only the version check; enableInstallTelemetry: false or PI_TELEMETRY=0 turns off install telemetry.

10. Common Commands Cheat Sheet

Source: README.md > CLI Reference

# Sessions
pi -c                          # continue the latest session
pi -r                          # browse past sessions
pi --name "release audit" -p "Audit this repository"
pi --session <path|id>         # open a specific session
pi --fork <path|id>            # fork from a specific session

# Models
pi --provider openai --model gpt-4o "..."
pi --list-models [search]

# Tool control
pi --tools read,grep,find,ls -p "Review the code"   # read-only
pi --exclude-tools ask_question                     # disable a single tool
pi --no-builtin-tools                               # turn off built-ins, keep extension tools

# Resource control (precise loading)
pi --no-extensions -e ./my-extension.ts
pi --no-skills
pi --no-context-files              # or -nc

# Package management
pi install <source> [-l]
pi remove  <source> [-l]
pi update --all | --extensions | --models | --self

Common in-session commands: /model /thinking /resume /new /tree /fork /clone /compact /session /reload /hotkeys /export /share /trust /settings /quit. Use /hotkeys to see all shortcuts; customize them in ~/.pi/agent/keybindings.json, then /reload.

11. An "Efficient Build" Checklist

A recommended setup assembled from the official capabilities:

1. Write an AGENTS.md at the project root: commands, conventions, red lines. Invest once, save time forever.
2. Save your default model/thinking level with Ctrl+S instead of switching every time.
3. Turn repeated prompts into prompt templates instead of retyping them.
4. Turn repeated multi-step workflows into skills, with a description that clearly states when to trigger them.
5. Split big tasks into stages: one session per stage; if things go off track, roll back with /tree instead of starting over.
6. Remember compaction is lossy in long sessions: have key conclusions written to files (TODO.md, design docs), not just left in context.
7. Need parallel/background work: start multiple pi instances in tmux; don't expect built-in background bash.
8. Need approvals/guardrails: write an extension or use --tools read-only mode; there are no official prompts.
9. Read the source before installing third-party packages: they have full system access.
10. For non-interactive pipelines, use -p / --mode json / --mode rpc / the SDK.

Official Docs Index

Install directory: /opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/

Pi can do this itself: just ask inside pi, "help me make a skill / prompt template". The official docs explicitly say pi can create skills / pi can create prompt templates.