Prompt Engineering in Pi

Pi is Mario Zechner's (Earendil Inc.) minimal terminal coding agent harness. It ships with four built-in tools (read, bash, edit, write — plus grep, find, ls) and a system prompt of roughly 300 words, making it one of the leanest agents available. The design principle is explicit: pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. No built-in MCP, sub-agents, permission popups, or plan mode — you build or install those.

Prompt engineering in pi is therefore about two things: (1) writing the context and system-prompt files that shape every session, and (2) composing extensions/skills/templates that encode your workflow instead of repeating it in prose.

Context Files — Your Project's Persistent Instructions

Pi loads AGENTS.md or CLAUDE.md at startup from:

• ~/.pi/agent/AGENTS.md — global instructions for every session
• Parent directories, walking up from the working directory
• The current working directory

If a directory contains AGENTS.override.md, pi loads it instead of AGENTS.md or CLAUDE.md from that directory. Disable loading entirely with --no-context-files (-nc).

Write context files as dense, command-oriented conventions:

# AGENTS.md

## Commands
- `npm run dev` — Start dev server (Next.js, port 3000)
- `npm run build` — Production build (type check, lint, bundle)
- `npx vitest run` — Run all tests
- `npx eslint .` — Lint check

## Architecture
- Next.js 15 App Router, React Server Components by default
- TypeScript strict, path alias `@/`

## Conventions
- Co-locate tests: `foo.spec.ts` next to `foo.ts`
- kebab-case components, camelCase utilities
- Server components by default; `'use client'` only for interactivity

System Prompt Files

Replace the default system prompt with:

• .pi/SYSTEM.md for a project
• ~/.pi/agent/SYSTEM.md globally

Append to the default prompt without replacing it with APPEND_SYSTEM.md in either location. This is pi's most powerful prompt-engineering lever — you can swap in your own 300-word operating manual and tune it precisely:

# My System Prompt

You are a pragmatic staff engineer. Rules:
- Ask one clarifying question before large refactors.
- Prefer small, reviewable diffs over sweeping rewrites.
- Always run the relevant test file after editing.
- Report token cost only when asked.

Use --system-prompt <text> to replace the default for a single run, or --append-system-prompt <text> to append.

Slash Commands for Prompt Workflows

Prompt Templates

Templates expand via /templatename — reuse proven prompts without retyping them:

<!-- ~/.pi/agent/prompts/code-review.md -->
You are reviewing a pull request. For each file:
1. List correctness bugs, then style issues, then performance concerns.
2. Suggest a fix for each bug — don't apply changes.
3. Flag any test gaps in the changed lines.
Keep the review under 300 words.

Type /code-review and pi expands the template into the editor for editing before sending.

Message Queue — Steering While Working

Pi's editor lets you submit messages while the agent is still working:

• Enter queues a steering message, delivered after the current turn finishes its tool calls.
• Alt+Enter queues a follow-up message, delivered after the agent finishes all work.
• Escape aborts and restores queued messages to the editor.
• Alt+Up retrieves queued messages back to the editor.

Configure delivery in settings with steeringMode and followUpMode. This makes multi-turn prompts feel like live pairing — you steer mid-execution instead of waiting for the turn to end.

Prompt Patterns for Pi

Pattern 1: Read-Only Analysis

Pi's tool allowlist makes safe analysis one-flag away:

pi --tools read,grep,find,ls -p "Review the auth middleware in src/auth/
for CSRF, session fixation, and token storage issues. Report findings only."

Pattern 2: File-Focused Review

Use @ file arguments to scope context precisely:

pi @code.ts @test.ts "Review these files: do the tests cover the edge cases
in code.ts? List any gaps."

Pattern 3: Compact-with-Instructions

When context runs long, compact with custom instructions to keep the thread focused:

/compact [Summarize what we've built so far. Keep the API decision,
the test list, and the remaining steps. Drop the exploratory dead-ends.]

Pattern 4: Fork-to-Clean-Thread

/fork
We decided to switch the DB layer from raw SQL to better-sqlite3.
Start a clean thread with that decision as context and design the schema.

Common Pitfalls

• Prose instead of packages — if you find yourself pasting the same 10-line instruction every session, turn it into a prompt template or skill.
• Missing context files — pi is minimal; without AGENTS.md conventions, every session starts from zero. Always set up context files per project.
• Over-trusting defaults — pi has no built-in permission prompts. Use --tools allowlists and --no-tools for untrusted or read-only work.
• Ignoring the trust flow — pi asks before trusting a project with local settings/skills. Review .pi/settings.json before trusting.

Related Pages

• MCP Setup in Pi — adding MCP support via packages and skills
• Pi Coding Agent (Agents Section) — platform overview and ecosystem
• Pi (pi.dev docs) — full usage reference
• Agent Skills (Agents Section) — cross-tool SKILL.md standard
• Jcode Prompt Engineering — the batteries-included alternative
• Tool Comparison — jcode vs pi vs opencode vs Claude Code