Pi is interesting when you want more say in how a coding assistant does its work. It runs in a terminal, uses a model you choose and can read files, search, run commands and edit code. You can then adapt it with saved prompts, task instructions and extensions. A recurring incident review shows why that might help: the same kinds of files arrive each time, and the next engineer needs a report they can check. The example below starts with those files, then explains where customization becomes worth the effort.
01Fit
02Requirements
Pi is MIT licensed; the model it uses has its own costs. A provider may charge for API usage or require a subscription, while a local model uses your computing resources. Check the provider’s current prices and data terms before sending private files or committing to repeated reviews.
Check current access and pricing03Setup
The npm command below requires Node.js 22.19 or newer. If npm does not suit your setup, the quickstart also has a standalone installer for macOS and Linux. Native Windows has a separate guide. Install Pi in the environment where you intend to run the review.
npm install -g --ignore-scripts @earendil-works/pi-coding-agentRun pi --version in that environment. A version number gives you something concrete to compare if a command or setting behaves differently after an update.
pi --versionStart pi, use /login to select an approved provider, then use /model to choose an available model. The login flow can store credentials, so use the credential-handling approach approved for that environment.
piPi runs with the permissions of the account that starts it and does not ask before every tool call. Choosing a working folder or a shorter list of tools does not restrict the whole process to those files. The security guide and full Pi article explain how to run this review in an isolated environment with read-only inputs.
04Using Pi
The starter’s checkout log contains two timeouts after a rollout, but also a successful request on the new revision. There is no downstream telemetry. Use Pi to turn these deliberately sparse, synthetic files into a handoff that says what happened, what remains uncertain and which evidence would help next.
Included example files
Synthetic code, logs, a deliberately stale runbook, and six support tickets. The JavaScript uses Node.js 22+ with no packages or network calls. Product accounts and model access are separate.
Read only the four files in operations/. Draft a handoff with observations, possible explanations, missing evidence and next checks. Cite filenames and line numbers for factual claims. Account for the successful request after the rollout as well as the timeouts. Compare the runbook with config.json. Do not invent downstream evidence or claim a root cause. Return the report in the conversation; do not edit the input files.The artifact you are working toward
A useful handoff connects events without treating timing as proof. The excerpt below is an authored illustration of the expected reasoning, not output from a Pi run.
Observed: r18 was rolled out at 09:10 UTC (rollouts.csv:3). Two subsequent requests time out at 2000 ms, but a later r18 request succeeds (checkout.log:2–4).
Documentation mismatch: config.json:1 sets 2000 ms and zero automatic write retries; runbook.md:3 says 5000 ms and two.
Unknown: whether the rollout caused the timeouts. No downstream telemetry is included. Compare revision-specific failures and downstream latency before choosing a cause.The bundle establishes ordering, not causation. Ask for the evidence that rules out competing explanations; none is provided here.
Point Pi back to config.json and ask it to preserve the disagreement. Confirming the deployed value would require evidence beyond this static bundle.
A colleague should be able to resume the investigation from the handoff and check its claims quickly. If checking the prose takes longer than reading the four files, simplify the request or the output before adding more tools.
The included baseline tests and evaluation script were checked locally. The deliberately failing contract tests demonstrate the defects in the starter. No AI product was installed or run for these examples; model responses and reviews will vary.
05Next steps
If you are repeatedly typing the same request, a prompt template may be enough. A skill can add the instructions and supporting material a review needs. An extension becomes useful when you need code to do something new, such as retrieve an approved incident export. The full Pi guide follows these choices through a related three-file review so you can see what each one adds.
Read the guidanceWhen a script starts a review, it needs to know when Pi has finished before it forwards the report. The full guide explains the differences between plain-text output, JSON event records and the RPC interface, which lets another program send commands and receive responses. It also covers MCP, the protocol Pi can use to call tools supplied by other services.
Read the guidance06Alternatives
07Evidence and scope
Product behavior is based on the linked official documentation. This walkthrough uses an authored synthetic starter project. Its baseline tests and local checker were checked; no installation, model response or product performance was independently tested for this guide.
Documentation checked