Pi Coding Agent Field Guide

Pi is a terminal coding agent that starts almost empty and grows through packages, skills, hooks, and project files. That is the opposite of many agents that ship fully loaded.

This post is a compact field guide: install and auth, security, sessions (/tree, clone, fork, compaction), packages, AGENTS.md, skills, prompt templates, extensions, and daily TUI habits. Prefer the official docs and pi.dev when flags drift.

What Pi is

Minimal, highly extensible terminal coding agent (TUI). Built-in surface is small
(read/write/edit/bash + a few helpers). Power comes from:

packages · skills · prompt templates (slash commands) · extensions/hooks · AGENTS.md

Philosophy: start lean, then shape the agent to your workflow - not the reverse.

---

1. Install, auth, model

# npm (common)
npm install -g @mariozechner/pi-coding-agent

# or package managers / binaries from pi.dev or GitHub releases
pi

First run often: no models until auth.

/login          # OAuth (subscription providers) or API-key path
/logout
/model          # switch mid-session (Ctrl+L / Ctrl+P cycle)

Auth file (preferred): ~/.pi/agent/auth.json
Env vars also work (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, …).
Auth file wins over env.

Caution: some “subscription” logins still bill extra API usage,
not the same included pool as the vendor’s own IDE agent. Prefer intentional auth.

Custom models (Ollama/vLLM/proxies): ~/.pi/agent/models.json
(live-reloads when opening /model).

---

2. Settings (two layers)

/settings                 # TUI toggles (subset)
~/.pi/agent/settings.json # global full config
./.pi/settings.json       # project overrides (merge)

Common toggles / fields:

Area	Examples
Compaction	compaction.enabled, reserveTokens, keepRecentTokens
Thinking	defaultThinkingLevel, hide thinking (Ctrl+T)
Queue	queueMode: one-at-a-time | all
Steering	how follow-ups inject while agent runs
Models	defaultProvider, defaultModel, enabledModels
Skills	skills.enabled
Packages	packages: ["npm:…", "git:…"]
Theme	theme, custom ~/.pi/agent/themes/*.json
Terminal	terminal.showImages

Advanced: edit settings JSON directly for options not in /settings.

---

3. Security model (critical)

Unlike some agents, Pi is broad by default once a project is trusted.

On start: trust prompt
→ trust project / parent folder / session-only / deny.

Trusted project ⇒ agent can read/write/exec with full tools.
If you need isolation: Docker sandbox (or similar) is the recommended hard boundary.

Typical hard isolation: Dockerfile + run Pi inside container so host FS is not exposed.

Complementary soft boundaries:

• packages that add guardrails (command/path policy)
• custom hooks that block sudo, rm -rf, writes to .env, etc.
• --tools to start with a reduced tool list

---

4. CLI startup flags worth memorizing

pi                         # interactive session (saves JSONL)
pi -c / --continue         # latest session for cwd
pi -r / --resume           # picker
pi --no-session            # ephemeral (no resume pollution)
pi --session path.jsonl    # explicit file
pi "initial prompt here"   # start + auto-send first message
pi --print "prompt"        # non-interactive / print mode (scripts, CI)
pi --tools find,read,ls,grep   # restrict built-ins (names as exposed)
pi --no-skills
pi --provider … --model …

Resume picker tips:

• Tab changes scope (cwd only → broader)
• search/filter shortcuts in the picker UI
• sessions are per working directory by default

---

5. Sessions (core mental model)

Everything happens in a session.

Action	Effect
pi / /new	Fresh context
Auto-save	~/.pi/agent/sessions/--<cwd-path>--/<ts>_<uuid>.jsonl
Format	JSONL tree: each entry has id + parentId
Continue	same branch grows
Clone	copy session at current tip → new file
Fork	copy from earlier message → new file
/tree	navigate in-place tree, no new file
/branch	branch into new session file via message picker
Compaction	summarize older turns to free context

Tree view (/tree) is the power tool:

• search, page, filter modes (default / no-tools / user-only / labeled)
• label bookmarks
• jump back and grow a side branch without losing history
• optional summary of abandoned branch when switching

Compaction:

/compact
/compact Focus on the API surface and open bugs

Auto-compaction (if enabled): on overflow error, or when near context window.
Lossy for the live prompt - full history still on disk; recover via /tree.

When context is polluted: prefer /new + a written plan file over grinding in junk context.

---

6. Everyday TUI usage

Editor

• @ fuzzy file reference (respects gitignore)
• Tab path completion
• multi-line: Shift/Alt+Enter
• Ctrl+G external editor
• Ctrl+C clear; double Ctrl+C exit
• Esc abort stream; Esc×2 earlier-state picker (tree-related)
• Ctrl+O expand tool output; Ctrl+T thinking visibility
• Shift+Tab thinking level cycle
• Ctrl+P / Shift+Ctrl+P model cycle

Bash mode (include shell output in context)

!git status
!ls -la src

Large output truncated (docs: ~2000 lines / 50KB). Esc cancels.

Message queue / steering

While agent runs you can type more:

• queue modes: process all vs one-at-a-time
• steering: inject mid-turn vs wait
• Esc aborts and restores queued text to editor

Plan without a dedicated “plan mode”: ask for a markdown/HTML plan file, iterate,
then implement from that artifact (a solid pattern).

---

7. Packages (third-party extensions)

Installable capabilities (tools, UI, behaviors). Catalog on pi.dev packages page.

In settings:

{
  "packages": [
    "npm:some-package@version",
    "git:github.com/org/repo@commit"
  ]
}

Common package patterns (names evolve - check the current catalog):

Goal	Package idea
Web research	web-access style package (search + fetch tools for the agent)
Safety	guardrails package (policies on commands/paths)
Parallel work	subagents package (spawn workers with fresh context, report back)
UX / workflows	many others - browse by downloads

Self-configure: because Pi is a coding agent with system access, you can ask it
to edit its own settings/packages - powerful and risky; review diffs.

After install: restart or reload as package docs require; new tools appear for the model.

---

8. AGENTS.md (always-on project brain)

Loaded at startup (merge order):

1. ~/.pi/agent/AGENTS.md
2. parents walking up
3. ./AGENTS.md

Use for: commands, architecture, conventions, test how-to, don’t-touch lists.
Not for heavy one-off workflows (skills) or short reusable prompts (slash commands).

Claude Code uses CLAUDE.md; Pi also reads it as alternate project context.

---

9. Skills (on-demand capability packs)

Agent Skills standard (SKILL.md). Loaded when description matches or forced:

/skill:my-skill-name optional args

Locations (recursive under Pi dirs):

• ~/.pi/agent/skills/**/SKILL.md
• .pi/skills/**/SKILL.md
• also discovers Claude/Codex skill trees

my-skill/
  SKILL.md          # name + description (critical for auto-trigger)
  scripts/
  references/
  assets/

Need	Prefer
Always-on conventions	AGENTS.md
User-triggered prompt template	slash command (commands/*.md)
New LLM-callable tool	custom tool / package
On-demand workflow + scripts + docs	skill

Local skill wins for token efficiency vs “please read the whole web docs every time”.
Global skills: cross-project helpers. Project skills: stack/domain specifics.

---

10. Prompt templates (slash commands)

Reusable prompts as markdown:

• Global: ~/.pi/agent/commands/*.md (docs path; some setups also use a prompts/ folder)
• Project: .pi/commands/*.md

---
description: Review staged git changes
---
Review `git diff --cached`. Focus on bugs, security, missing tests.

Filename → /filename. Args: $1, $@.
Subdirs namespace commands.

Use when you keep retyping the same multi-paragraph instruction.

---

11. Extensions / hooks (deep customization)

Hooks = TypeScript modules on lifecycle events (tool_call, session_start, …):

• block dangerous tools
• checkpoint git state
• protect paths
• inject external wake-up messages

Paths: ~/.pi/agent/hooks/*.ts, .pi/hooks/*.ts, or settings hooks: [].

Custom tools = new tools the model can call (TypeBox params, optional TUI UI).

Paths: ~/.pi/agent/tools/*/index.ts, .pi/tools/*/index.ts, settings customTools.

Extension idea: after each turn, open last assistant message as rendered HTML
(summary/readability) - implemented as extension, preferably global.

Packages are the distributed form of extensions/tools/hooks.

---

12. Workflow patterns

1. Bootstrap project brain - AGENTS.md + stack skills before heavy coding
2. Plan as artifact - markdown/HTML plan file, refine, then implement
3. Discuss then build - architecture critique in-session, then code
4. Commit via agent - !git … or natural language commit (still review)
5. Feature branches of thought - /tree or /fork when exploring alternatives
6. Keep context clean - ephemeral for one-shots; new session when topic shifts
7. Docs-first skills - for young frameworks, pin official docs in a skill
8. Manual skill activation when auto-discovery is unreliable

---

13. Pocket command map

Command / action	Purpose
/settings	Quick settings
/model /login /logout	Models & auth
/new	Fresh session
/session	Path, tokens, cost
/resume -r	Session picker
--continue -c	Last session
--no-session	Ephemeral
/tree	In-place branch nav
/branch /fork /clone	Copy/branch sessions
/compact	Summarize old context
/export	HTML export
/hotkeys	Shortcut list
/copy	Copy last assistant msg
@file	Attach project file
!cmd	Shell → context
/skill:name	Force skill
/command	Prompt template

---

14. Layout on disk (cheat)

~/.pi/agent/
  auth.json
  settings.json
  models.json
  AGENTS.md
  SYSTEM.md                 # optional full system prompt replace
  sessions/--path--/*.jsonl
  packages / hooks / tools / skills / commands / themes / extensions …

project/
  AGENTS.md
  .pi/
    settings.json
    skills/…
    commands/…
    hooks/…
    tools/…
    SYSTEM.md

---

15. Decision tree

Always true for this repo?          → AGENTS.md
I retype the same prompt weekly?    → slash command / prompt template
Need scripts + workflow docs?       → skill
Need new tool the model calls?      → package / custom tool
Need to block/modify behavior?      → hook / guardrails package
Need isolation from host?           → Docker (or stronger sandbox)
Context full / polluted?            → /tree branch, /compact, or /new + plan file
Quick throwaway Q?                  → --no-session

---