Pi.dev: a coding assistant you can adapt to your work

Three files can contain the beginning of an incident explanation without yet adding up to one. A deployment history names the change, a log records the slow requests, and a runbook suggests where to look. Someone still has to connect their timestamps, distinguish a plausible lead from a demonstrated cause, and decide what evidence to collect next. That is a useful, contained job to give a coding assistant.

Pi runs in a terminal and can work through files on your machine using a model you choose. It can read and search, run commands, and edit code. For this job, the interesting capability is simpler: can it turn a small evidence bundle into a report that another engineer can check without repeating the entire investigation?

Pi lets you adapt the tools and instructions around that work. You can remove unnecessary tools, preserve a useful request for next time, or eventually connect an evidence service. Those choices make more sense once there is an actual task to improve. The hypothetical review below starts with three files and follows what happens from the first model request to the engineer’s decision about the report.

Give the assistant a useful question and a deliberate gap

In this hypothetical example, checkout becomes slower after a deployment. The trial uses a sanitized folder with three inputs: deployments.csv supplies revisions and rollout times; checkout.log supplies selected timestamped events; and runbook.md supplies the investigation procedure. Credentials and private customer details have been removed. The question is what those files establish about the slowdown and which check should come next.

Leave downstream-service information out of the folder deliberately. That missing evidence gives the trial a revealing test: does the report recognize that checkout’s dependencies remain an open question, or quietly write as though they have been ruled out? An assistant can be useful without solving the incident. It has to make the limits of its explanation visible enough for the next engineer to work with.

A suitable request is: “Review these files, separate observations from hypotheses, cite the filename and line numbers behind each factual claim, and suggest the next checks.” If the log places the first slow requests near the rollout, the report can connect the two and suggest inspecting the changed code. The references let a reviewer test that connection directly, rather than trusting a polished description of it.

The result is worth adopting only if another engineer can locate the next decision, inspect its evidence, and accept or reject it with less effort. That includes the time spent checking the report. Finishing the model’s work is an intermediate step; making the human review easier is the point of this exercise.

A bounded Pi investigation

Read diagram description

A sanitized evidence bundle is mounted read-only. Pi reads and searches it without production credentials. Its candidate report separates cited observations, hypotheses and missing evidence. An engineer checks the claims against the original files before accepting a useful next check. Any later production action requires separate authorization and independent outcome verification.

Follow one file read around the agent loop

Pi sends the chosen model the task, conversation so far, relevant instructions and descriptions of its tools. The model can then ask to read deployments.csv, inspect checkout.log, or search for an error it has found. Pi executes the requested operation and sends back its result. The model uses that new information to ask for another operation or produce an answer. The repeating exchange, described in the documentation on how Pi works, is what lets the assistant investigate files rather than merely talk about them.

The available operations determine how far that investigation can go. Pi’s usual tools include read, bash, edit and write, covering file inspection, shell commands and code changes. Our report does not need all of them. Pi also offers grep, find and ls; the --tools option replaces the selected set for a run. A reading-and-search selection gives this task the relevant operations without offering editing capabilities it does not need. The CLI reference lists the exact choices.

The software coordinating those model calls, tool results and conversation entries is the agent harness. Pi can branch the conversation to explore another lead, and in a long session it can summarize older material for later model requests while retaining the original entries. That makes it possible to revisit an earlier line of inquiry, but it also means the saved session can contain the evidence read from the files. Treat it with the same care as the logs themselves. Pi’s session guide explains the storage and summary behavior.

Customize the part that actually costs you effort

After a useful first report, there may be no need to write code. A prompt template can preserve the request, and a skill can supply instructions and supporting material, such as the team’s distinction between an observation and a hypothesis. These small additions address a recurring nuisance: getting the next review started with the same clear question and expectations.

Code becomes useful when the workflow needs a new operation. An extension is a TypeScript module that can add tools, respond to events or alter the information sent to the model. For this example, an extension could retrieve an approved incident export instead of requiring a manual download. The extension guide describes those building blocks. Reviewed prompts, skills and extensions can travel together as a Pi package; pinning its version lets reviewers know which shared setup produced a report.

Pi 0.99.0, released September 29, 2026, added another route to those services through built-in Model Context Protocol support and Codemode. MCP gives the assistant a common way to discover and call tools exposed by another program. If an evidence service provides an appropriate MCP connection, Pi could obtain the bundle through that interface. The investigation question can stay the same even though the way its inputs arrive has changed.

Codemode lets the model compose tool operations with JavaScript. A connected operation could fetch the incident export and another could list relevant deployments, bringing both results into the investigation. The MCP documentation covers configuration, and Earendil’s explanation of the release explains the design choice. Neither capability is necessary to judge the three-file trial. They earn their place later if obtaining and combining the evidence is the part of the process that needs improvement.

The missing evidence is part of the answer

Now return to the hypothetical report. Suppose it recommends inspecting the deployment because the slowdown begins soon afterward. Its cited lines should let the reviewer confirm that timing. They cannot, by themselves, prove causation. A further claim that checkout’s downstream services were healthy would be more revealing: the bundle contains no evidence for it. Catching that unsupported step is part of judging the assistant’s usefulness, not a minor copy edit.

Keep the report beside the original files and mark the findings that helped, the claims that needed correction, and the proposed checks an engineer could actually perform. Record how long this review takes. A fast generation followed by a laborious fact-check may save no work at all; a modest report with accurate references and a clearly stated gap may make the next decision much easier.

When maintaining your own setup is worth it

Pi is attractive when its flexibility removes a recurring difficulty: assembling the right inputs, asking a consistent question, or producing a report whose references are easy to inspect. That is also the comparison with an existing tool. If the current tool already supports the investigation well, maintaining a custom Pi configuration introduces work that needs a concrete justification.

Some difficulties belong elsewhere. If engineers mainly need to see which coding session is waiting for attention, the Herdr guide addresses that supervision problem. Pi is more relevant when the team wants to change how an individual assistant carries out its task.

If checking Pi’s report takes longer than doing the investigation directly, revise the question, inputs or model before connecting additional systems. If reports repeatedly reduce the effort of deciding what to do next, further customization has a reason to exist. That still does not authorize deployment changes: each later write needs an allowed target and action, plus checks against current state, as the guide to operational agent skills explains.

The rest of this guide shows how to run the limited exercise and how to recognize completion when it becomes automated. These details serve the same question as the report review: can the surrounding process make this a dependable, repeatable piece of work?

Set the limits around the whole process

For the first exercise, put the complete Pi process inside a suitable container or sandbox and mount only the sanitized folder, read-only. Omit production credentials and permit only the approved model connection. The report can then be evaluated without giving the assistant a route to make production changes.

A prompt asking Pi to stay in a folder cannot provide that protection. Pi uses the account permissions of the process running it, and selecting a working directory does not confine later access to that directory. Nor does Pi ask before every tool call. Project trust decides which project settings and resources load; it is not a comprehensive restriction on subsequent actions. The security guide makes that distinction explicit.

The placement of extensions matters for the same reason. When Pi and its extensions run inside the isolated environment, both are subject to that environment’s limits. Sandboxing only selected tools while leaving Pi on the host can leave other extensions executing on the host. Even a fully isolated process can use files, credentials and network access that you deliberately expose to it. The isolation guide compares these arrangements and their setup.

With the boundary prepared, use the official quickstart to install Pi. The npm package is @earendil-works/pi-coding-agent, requiring Node.js 22.19 or newer. Record pi --version and select an approved model provider so the trial can be reproduced. Installing the harness does not supply model access; its price and permission to process the supplied files need to be checked separately.

The following illustrative invocation requests the report with file-reading and search tools after the environment and model provider are configured:

pi --no-approve --no-extensions --no-skills \
  --no-prompt-templates --no-context-files \
  --tools read,grep,find,ls --print \
  "Review deployments.csv, checkout.log and runbook.md.
   Separate observations from hypotheses.
   Cite filenames and line numbers for factual claims.
   Identify missing evidence and propose the next checks."

The name --no-approve is easy to misread: it skips trust-gated project resources rather than enabling approval prompts. The other resource flags reduce customization loaded into this run, while --tools selects the built-ins listed in the command. These are documented in the CLI reference. They help define the experiment, but the environment remains responsible for limiting what the process can reach.

Teach the surrounding script what “finished” means

If the manual exercise proves useful, a script might start the same review when a new bundle arrives. It must know when to collect the result and when to report a failure. In print mode, a final assistant response marked error or aborted causes Pi to signal an error to that script.

JSON mode needs different handling. It emits one JSON record per line describing the work, but a failed or aborted assistant response does not by itself produce an error exit status. The caller must inspect the records. A stream made of JSON records also does not guarantee that the model’s final answer has the report structure your program expects.

A longer-running integration can use RPC to send commands and receive responses. An accepted prompt response may mean only that the request was accepted or queued. Wait for agent_settled to establish that automatic work has settled; agent_end may still be followed by recovery or queued work. The CLI integration documentation explains the distinction. At that point the program can deliver the report for review, not silently treat it as an accepted conclusion. The guide to evaluating incident-response agents develops that evaluation step.

MCP adds one final failure case to plan for. Pi supports local servers over stdio and remote servers over streamable HTTP, with OAuth for remote sign-in. It may retry a temporarily failed resource read, but does not automatically retry a tool call: the server might already have performed the action. If later tools can change state, preserve an unresolved result and inspect what happened before repeating it. The MCP documentation documents this behavior. The same habit that makes the three-file report useful carries through the integration: keep enough evidence to tell what happened, what remains uncertain, and what the next person should do.