---
title: "Pi Coding Agent Field Guide"
url: "https://vanducng.dev/2026/08/16/pi-coding-agent-field-guide/"
date: "2026-08-16"
categories: ["AI"]
tags: ["agentic-coding","pi","coding-agents","tui"]
---

# 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](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) and [pi.dev](https://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

```bash
# 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.

```text
/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)

```text
/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

```bash
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:

```text
/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)**

```text
!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:

```json
{
  "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:

```text
/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

```text
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`

```markdown
---
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)

```text
~/.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

```text
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
```

---