Newsletter, guides

Use the pi coding agent for code review, docs and triage

Practical prompts for the pi coding agent: code review, docs, issue triage and research over local files, with the model to pick per task and measured cost.

, 7 min read, updated

The pi coding agent fits small, focused jobs that have a clear check. Examples are a diff review, one docs section, a list of issues to label, or a question about files on disk. Each of those finished within 13 seconds and cost less than a cent on Claude Haiku 5.5 in my tests.

This guide gives the prompt templates I use, the model I pick for each job, the measured cost, and the jobs where pi is the wrong tool. It assumes pi is already set up as in the setup guide for pi with a Claude API key.

Key takeaways

  • Give pi one job per run, with a named file and a clear output. Vague prompts make the agent search, and searching is where tokens go.
  • Run one-off jobs with pi -p --no-session. A session you do not need to resume carries no history cost.
  • Save each repeated job as a prompt template. A template in ~/.pi/agent/prompts/ becomes a slash command.
  • Start every job on Haiku 5.5. Move to Sonnet 5.5 for review that must catch subtle bugs, and to Opus 5.5 for design questions.
  • Pi is the wrong tool for large cross-repo refactors, anything that needs a browser, and work where a human must approve every step.

What is the pi coding agent good for?

Pi is a small terminal agent with four tools: read, bash, edit and write. It sends a short prompt and lets you pick the model. That makes it cheap and quick on tasks where the input is a few files and the result is a short answer or a small edit.

Four jobs fit that shape well. They are code review of a diff, docs written from code, triage of a pile of issues, and research over local files.

Each has a natural check.

A review names a file and line. A docs section has a runnable example. A triage table has a label per row. A research answer cites the file it read.

Decision flow that routes a pi task to a one-shot or interactive run and then to Haiku, Sonnet or Opus by task type

How do you review code with pi?

Make a prompt template, then call it with /review. This is the file I keep at ~/.pi/agent/prompts/review.md.

---
description: Review a diff or the staged changes for real bugs
argument-hint: "[file or focus]"
---
Review ${1:-the staged changes (git diff --staged)}. List only real bugs: wrong behavior, security holes, missing checks. One line each with file and line. If there are none, say so. Do not edit anything.

The last sentence matters. A review run should not change files. For extra safety, limit its tools so it cannot write.

git diff main... > /tmp/change.diff
pi -p --no-session --tools read,bash "Review /tmp/change.diff. List only real bugs, one line each with file and line."

With the tools limited to read and bash, my starting prompt dropped from 2,407 to 1,694 tokens. In my test the diff had a seeded bug. Haiku found it for $0.0004. Sonnet cost $0.0097 and Opus $0.0212 on the same review.

Use Haiku for the first pass on every change. Run Sonnet on changes that touch auth, money or data deletion, where a missed bug is costly. Treat pi as the quick first pass, and keep a human review for anything that ships.

How do you write docs with pi?

Point pi at one file and ask for one section. Docs written from “the project” invent features. Docs written from a named file describe what the code does.

---
description: Write or update docs from the code
argument-hint: "<file> [section]"
---
Read $1 and write the ${2:-usage} section for it. Use only what the code does. Short sentences, one runnable example. Edit the docs file in place.

Call it as /docs shop/retry.py usage. The phrase “use only what the code does” is the guard. Then run the example. A docs section whose example does not run is a bug, and pi will not tell you.

On my retry module, Haiku wrote the section for $0.0007 in 9 seconds. Sonnet cost $0.0065. I could not tell the outputs apart on a short module. Pay for Sonnet when the module has subtle behavior that the docs must get exactly right, such as retry limits and backoff.

How do you triage issues with pi?

Export the issues to a file and ask for a table. Triage is classification, which is the job small models do well.

---
description: Label issues from a file
argument-hint: "<issues file>"
---
Read $1. Label each issue bug, feature or question, with one short reason. Output a table. Do not edit anything.
gh issue list --limit 50 --json number,title,body > issues.json
pi -p --no-session "/triage issues.json"

My triage run on Haiku used about 5,300 input tokens and cost $0.0004. Sonnet cost $0.0058 and Opus $0.0116 for the same labels. Check a sample of rows against your own judgment before you trust the labels, and never let the run close or label issues on its own.

How do you research local files with pi?

Name the folder and the question, and ask for the file that supports each claim. Pi reads files with its read tool, so the answer is only as good as the files you point at.

pi -p --no-session "Which module retries failed calls, and how long does it wait? Quote the lines and name the file."

My research task read two files and used about 8,000 input tokens. Haiku answered for $0.0004, Sonnet for $0.007 and Opus for $0.015. All three gave the right answer.

Pi reads local files and runs commands. It is not a web search tool. For research that needs the web, use a tool built for it and bring the findings into a file that pi can read.

Which model should you pick for each job?

Start on Haiku 5.5 and move up when a job fails or the cost of a miss is high. These are my defaults.

Job Model Why
Triage, summaries, research over a few files Haiku 5.5 Classification and lookup pass at the lowest cost
First-pass review, docs from short modules Haiku 5.5 Passed in my test, so no reason to pay more
Review of risky changes, subtle docs Sonnet 5.5 A missed bug costs more than the model
Small edit with a test Sonnet 5.5 when Haiku fails Fewer retries on multi-step edits
Design questions, hard bugs Opus 5.5 Use it rarely, on one call

On the edit task, which needed several tool turns, Haiku used 13,139 input tokens and Sonnet 19,114. Both passed. Retries and re-reading files drive cost on edits more than the model price does. Name the file and the test command in the prompt so pi does not search.

Switch with Ctrl+P during a session. Read the guide to choosing a model per task for the general method.

When is pi the wrong tool?

Pi does not fit work that is large, visual or high stakes.

  • A refactor across many files needs a plan, test runs and review. Use an agent with planning and verification built in.
  • Anything that needs a browser or a screenshot is outside pi’s four tools.
  • Work where a human must approve each command needs a permission layer. Read how to scope a bash tool safely before you give any agent a shell.
  • A task you cannot check is a task you cannot trust. Do not use pi for it.

My results come from small tasks. They show where to start, and they do not show how pi performs on a large codebase. Run your own five tasks before you rely on these defaults.

What to do next

  1. Save the three templates above into ~/.pi/agent/prompts/.
  2. Run /review on your next staged change, on Haiku.
  3. Run /triage on an exported issue list and check a sample of rows.
  4. Run /docs on one module and execute the example it writes.
  5. Record input tokens and cost with pi -p --no-session --mode json for each job, and note which jobs need Sonnet.
  6. Learn how the loop behind these agents works in the coding agent event loop guide.
  7. Build one yourself in the free autonomous Claude Code agent session.

Frequently asked questions

What is the pi coding agent used for?

Pi is a terminal coding agent for small, focused jobs: reviewing a diff, writing a docs section, labeling issues and answering questions about local files. It has read, bash, edit and write tools, and it works with several model providers, including Anthropic.

Can pi do code review?

Yes, as a first pass. Run a short review prompt on a diff with read-only tools and ask for one line per bug with file and line. Haiku 5.5 found a seeded bug in my test for $0.0004. Use Sonnet 5.5 for risky changes.

How do I run pi without a session?

Use print mode with no session: pi -p --no-session "your prompt". Pi answers once and exits, and it keeps no history. Add --mode json to get usage events that show token counts and cost.

Does pi replace Claude Code?

No. Pi is smaller and cheaper for focused jobs. Claude Code carries planning, subagents, hooks and a permission system for larger work. Use pi when the job is one file and one check.

How much does a pi run cost?

On Haiku 5.5, my five small tasks cost between $0.0004 and $0.0008 each. On Sonnet 5.5 they cost $0.0058 to $0.0143, and on Opus 5.5 $0.0116 to $0.0236. Your cost depends on how many files pi reads.

Sources

Build what you just read, with Param, live

  1. You read the guide

  2. Free Live LabBuild a Second Brain with Claude CodeA second brain over your notes, docs and Linear that answers with sources and serves the same memory to any agent over MCP.Free seat
  3. ProWatch the video coursesDesign a Software Factory for Your Coding Agents, Build Your First Software Factory Execution Harness and each new course as the sessions are cut. The first lesson of each is free after you sign in.$149 a year
  4. WorkshopAI Agents in Production for EngineersA multi-agent system deployed with an identity per agent, permissions, guardrails, an LLM gateway, traces and evals, plus a checklist for your own agents.$497
  5. BuildcampAgentic AI Buildcamp for Engineers & PMsDesign, build and deploy a production agentic AI system in four weeks$997

Or watch the recording: Build an Autonomous Claude Code Agent

Subscribe to Top 1% Engineers

One issue at a time on building AI systems that hold up in production: architecture, the open source that matters, and what to do on Monday. Every number cited.

We email you each new issue. You can leave at any time. Privacy

More guides

See the newsletter and every guide