Pi.dev: a coding agent that can grow around your work

The utility accepts “2s” happily. Give it “250ms” and it tries to turn “250m” into a number. Once you see the function, the mistake is almost obvious. Finding it, repairing it and checking the callers is the rest of the afternoon. Pi is an open-source terminal agent that can work through those steps in the project and bring the results back to the conversation.

You can start with the agent as it comes. If you keep typing the same request, turn it into a slash command. If a procedure needs references, make it a skill. If an operation is missing, add an extension. Pi’s appeal is that the assistant can grow around your work without requiring you to adopt somebody else’s whole workflow.

There is a balance to strike. Time spent improving the assistant is time not spent on the utility. Start with work Pi can already do, then let a recurring annoyance make the case for customization.

What happens between a question and a test result

The model decides what to say or try next. Pi provides the instructions, tools and conversation history, then returns each tool’s result for the next decision. That surrounding software is an agent harness: the part that turns a proposed step into work in the project.

A failing test shows the loop in practice. The model requests the test file, then the implementation, then an edit and a test run. Pi performs the operations and returns their results, as Pi’s agent-loop documentation describes. The next response can use what happened in the repository instead of merely suggesting what you should try. A failure can lead to another attempt; a pass still leaves a diff to review.

The arrangement has a few distinct roles, and you can choose different products for several of them:

You can use Pi directly through its terminal interface; it is not just a framework waiting for you to build an application. Developers can also embed it with the SDK or control a process through RPC, a command-and-event interface between programs. Those are extra ways into the machinery, not prerequisites for asking about a function. SDK documentation.

This is the Pi at pi.dev, with source in earendil-works/pi. The name is shared elsewhere, but this is neither a Raspberry Pi setup nor a guide to another chatbot.

Why the core started small

Mario Zechner’s November 30, 2025 development essay described wanting control over model context, sessions he could inspect, multiple providers and a coding tool that did not keep adding unused features. The project separated model access, the agent loop, the terminal interface and the coding application.

That history explains the small core. It is a deliberate preference, not a promise to eventually copy every competing interface. Planning workflows and delegation to other agents can be added through extensions and packages, leaving you to choose the arrangement instead of requiring everyone to use it.

Some choices changed as the project developed. The original essay argued against built-in MCP support. Later, Pi 0.99.0 added MCP and Codemode on September 29, 2026, and Earendil announced Pi 1.0 on October 1. An old list of things Pi does not do is therefore no substitute for its current documentation.

The same 1.0 announcement introduced Pi Durable, an experimental package for longer-running agent applications. It is related work, not a prerequisite for the terminal agent. Earendil describes the separation as a way to explore those applications without putting every responsibility into the coding tool.

Choose Pi for the work you want to change

Pi fits naturally where files and a terminal are already part of the day. A developer can implement and review a change. A platform engineer can connect repository conventions and internal tools. A researcher or technical writer can keep scripts, datasets and notes together. An agent-product developer can reuse the existing session and tool loop rather than build it again.

These are possible fits, not a claim about Pi’s most common users. What they share is a reason to care about the setup: a report format to supply, an internal operation to add, or a provider to change while keeping the surrounding workflow recognizable.

For a team, “works for me” becomes less reassuring when it means three plugins nobody else has. Keep the shared setup small enough that someone can explain it. Add the piece that removes a real annoyance, rather than the one that merely looks interesting to configure.

Another tool may fit the work better:

• Work centered on an editor: Cursor puts agent work beside editing. If reviewing changes there matters more than adapting the harness, it may fit better than rebuilding that experience in a terminal.
• A more integrated coding assistant: Claude Code offers terminal, IDE, desktop and browser surfaces, with customization and automation of its own. Compare it when you want an established workflow around Claude; Pi is not the only customizable option.
• Another open tool with model choice: OpenCode is a closer comparison for provider flexibility. Try the interaction and configuration, since a shared ability to use many providers does not decide which feels useful for your work.
• One occasional question: ordinary chat may be sufficient for a pasted function. Installing a local agent could add more work than that explanation requires.

Compare the tools on the same real task, including the time you spend reviewing. Can you find the important decision, follow the supporting material and accept or reject the result more easily? That is more useful than judging how impressive the terminal looked while it was busy.

Make the first session small enough to understand

Use a disposable folder of non-sensitive files you understand for the first session. You can judge its answer and recover from accidental edits. Default tools can read, write, edit and run shell commands, without approval before every operation. If that is too much access, prepare a container or sandbox first; the isolation guide covers whole-process options.

This route uses npm on macOS or Linux, making the package explicit for readers already managing Node.js. It requires Node.js 22.19 or newer. Check the prerequisite, install, then inspect the Pi version:

node --version
npm --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

The --ignore-scripts flag disables dependency lifecycle scripts, which normal Pi npm installation does not require. The official quickstart also provides an installer with pinned dependencies. npm does not pin every transitive dependency, so record the installed version and keep a reproducible environment for team evaluation. Native Windows readers should consult the Windows setup for Git Bash and WSL choices before adapting these shell commands.

Installation and model access are separate. Choose one supported hosted provider you are already authorized to use, with suitable costs and data-handling terms for these files. The restricted launch below disables built-in extensions, including llama.cpp integration; local models have a separate setup later. One model is enough to see whether the first task makes sense.

Enter the disposable folder and give the first session reading and search tools:

cd /path/to/pi-playground
pi --no-approve --no-extensions --no-skills \
  --no-prompt-templates --no-context-files \
  --tools read,grep,find,ls

This launch excludes project customizations on purpose. --no-approve skips trust-gated project resources; it does not request approval for every later action. Selecting reading tools is convenient for this task, not an operating-system sandbox. The CLI reference documents the options.

Choose a provider with /login and follow its authentication flow. Open /model, select an available model and press Ctrl+S in the picker to save the startup default. That matters when a later command opens a new session. The provider guide explains API-key and OAuth methods. Since /login saves credentials, keep the authentication files private.

When a sandbox supplies proxy credentials, follow that setup instead of logging in inside it. The Docker Sandboxes instructions specifically say to configure credentials first and not use /login in the sandbox. Downloads and authentication may need network access during preparation; runtime access can be tightened afterward.

Ask a question you can check: “Explain the files in this folder, identify the main entry point, and tell me how the documented checks are run. Do not change anything.” The useful answer names real files and connects them. You should not have to decide whether an invented architecture sounds convincing.

Point the agent at the files that matter

The terminal shows conversation, tool activity and an editor for your requests. Type @ to find a file. “Compare @README.md with @package.json and identify setup instructions that no longer match the scripts” tells the agent where to look and gives you a result to review. “Improve the docs” leaves both much less clear.

Use /model to switch models and /session to inspect session information and reported usage. Give the session a recognizable name with /name. Escape stops a run but cannot undo an operation already performed. The terminal guide also explains steering current work versus queuing a follow-up.

A coding task needs another session with the appropriate tools. A normal pi launch enables read, write, edit and shell tools by default. That can be convenient in a trusted repository. In an unfamiliar one, inspect its instructions and project resources before enabling them. The restricted launch above is deliberately a reading setup, not the full coding environment.

Give the work a destination: “Add support for millisecond values, keep the public function name, and run the unit tests.” It names an outcome, a limit and a way to judge the result. “Make this production-ready” leaves much more to negotiate.

You need not dictate every tool call. Choosing intermediate steps is part of the reason to use an agent. You supply what the work is for, which changes are acceptable and what would make the result convincing.

Four useful results to ask for

The following tasks are constructed teaching examples. They show ways to frame and inspect work, not tasks Pi completed for this guide.

1. Repair the milliseconds without breaking seconds

Return to the small Python utility that converts a duration into seconds:

def seconds(value):
    return float(value[:-1])

For "2s", dropping the final character leaves a number. For "250ms", it leaves "250m". “Fix the parser” still leaves choices about units and accepted input. This request gives it a contract:

Update seconds(value) to accept non-negative decimal values followed
by ms or s. Allow surrounding whitespace. Reject missing units,
negative values and other suffixes with ValueError.
Preserve the function name. Add tests for 250ms, 2s, 1.5s, 0ms,
and invalid inputs. Run the tests and explain the change.

Save the function in a disposable project and enable Pi’s normal editing and shell tools there. When it finishes, inspect the diff and the tests together. Dividing every value by 1,000 could appear to repair milliseconds while quietly breaking seconds.

This hand-written reference implements the stated contract:

import re

def seconds(value):
    match = re.fullmatch(r"([0-9]+(?:\.[0-9]+)?)(ms|s)", value.strip())
    if match is None:
        raise ValueError("Use a non-negative number followed by ms or s")
    number, unit = match.groups()
    return float(number) / 1000 if unit == "ms" else float(number)

The expected values are 0.25, 2.0, 1.5 and 0.0 seconds. Inputs "2", "-1ms" and "3min" should raise ValueError. Scientific notation and shorthand such as .5s are intentionally outside this pattern. If the application needs them, change the contract and tests rather than accepting whichever interpretation the model chose.

The function is only the center of the repair. Pi can also find callers, change tests and run the project checks. Read those surrounding edits: a weakened test can approve the old mistake just as readily as the corrected behavior.

2. Follow one request through unfamiliar code

In an unfamiliar repository, the difficulty comes earlier: which file should you even ask about? Try a reading task: “Trace one request from the public API entry point to storage. Name the files and functions involved, and explain where validation and retries happen. Do not edit anything.”

Now the reading tools have a route to follow. Instead of touring directories, the answer should explain a behavior. Open the named functions and inspect a couple of transitions. If retries happen only for a particular error, that condition belongs in the explanation.

Then ask, “Which test would fail if validation were removed?” The answer connects the architecture to executable evidence, or reveals a gap worth discussing. Pi can help write a regression test afterward, with the behavior it protects already understood.

3. Keep the document’s claims attached to its sources

The same folder-based work can produce release notes, research summaries and technical documentation. Supply the sources and ask for traceable claims: “Draft release notes from these change summaries. Group user-visible changes, separate fixes from breaking changes, and flag anything that needs an upgrade action. Do not infer performance improvements.”

“Replace cache implementation” does not say the software became faster. An internal refactor may not belong in customer release notes at all. A useful draft describes effects the notes support and marks the questions they leave unanswered.

For a documentation comparison, supply two setup-guide versions and the relevant configuration examples. Ask for disagreeing commands, filenames and defaults, with references. That gives the editor a concrete result to inspect without first building a browser integration or a team of agents.

4. Compare the counts before describing the change

Pi can write and run small analysis programs when a CSV export becomes too awkward to compare by eye. Suppose two exports contain service, requests and errors. Ask it to join by service, report missing services separately and calculate error rates from the counts. Keep the script and calculation with the explanation.

Use simple arithmetic to check the interpretation. In an invented example, 10 errors out of 1,000 requests is 1%; 12 out of 2,000 is 0.6%. The error count rose by two while its rate fell. “Worse reliability” would need a more specific explanation of the measure. Zero requests needs an explicit missing or undefined rate, not a made-up zero or a division error.

For incident work, provide sanitized deployment history, request logs and a runbook. Ask for observations, hypotheses and missing evidence separately. A rollout at 10:00 followed by two slow requests is a lead, not proof of a service-wide percentile or a deployment-caused delay. Keep the original files with the answer for the next engineer to inspect.

A bounded Pi investigation

Read diagram description

In this illustrative workflow, the sanitized bundle is mounted read-only and Pi has no production credentials. It reads and searches the files, then produces a candidate report with cited observations, hypotheses and gaps. An engineer checks those claims before accepting a useful next check. Any later production action needs its own authorization and independent outcome verification.

Each task leaves something tangible: a patch, a cited explanation, an analysis script or a source-backed document. You can accept it or ask for a correction. Tool activity scrolling past is not the same kind of result.

Let the repeated task choose the customization

Once the work is useful, look at what you keep repeating. Pi offers several customization mechanisms because repeated wording and a missing operation are different problems. Choose the smallest one that removes the effort.

Project instructions keep shared facts close

For repository conventions that matter across tasks, an AGENTS.md file can state test commands and areas requiring care. A small Python project might use this:

# Project instructions
Use the existing public function names.
Run python -m unittest discover before reporting code changes complete.
Keep unit conversions explicit in function names and tests.
Do not edit generated files; update their source instead.

Put durable, useful facts here rather than a ten-page wish list competing with the task. Pi discovers context files in the working directory, parent directories and user configuration. They are separate from trust-gated .pi resources. If behavior surprises you, inspect what loaded. Configuration documentation.

A prompt template saves the question you keep typing

If the repetition is a question, turn a Markdown file into a slash command. In a project you control, save this as .pi/prompts/review-change.md:

---
description: Review a change against its intended behavior
argument-hint: "[focus]"
---
Review the current change, focusing on ${1:-correctness and tests}.
Explain the intended behavior, identify concrete risks with file references,
and distinguish a demonstrated defect from a question needing more context.
Do not modify files.

Review and trust the project resources, run /reload, then use /review-change or /review-change "backward compatibility". The filename becomes the command name and the argument supplies its focus. This is reusable text, not a new operation or enforcement of “do not modify.” Prompt-template guide.

The stripped-down first launch disabled this feature. Remove --no-prompt-templates and make a deliberate project-trust decision before expecting the template to appear. For a read-only mount, edit the host-side source and expose the updated files rather than asking Pi to write through the mount.

A skill brings the procedure and its references

A procedure may need more than one reusable paragraph. Put its method, examples and any supporting script in a directory containing SKILL.md. The skill’s name and description help Pi decide when it applies; detailed instructions load when needed. You can also request it explicitly with /skill:name.

A release-notes skill could bundle audience rules, the previous format and a script extracting approved change summaries. The procedure gains a consistent starting point without loading all that material into every coding conversation. Keep scripts inspectable and references relative to the skill directory. Skill documentation.

Extensions and connected tools add behavior

When the missing piece is behavior, an extension can supply it. Executable TypeScript inside the Pi process can add a tool or command, handle events, influence context and change the terminal interface. Fetching an approved build report or displaying project-specific status might justify one. Arbitrary executable code needs closer scrutiny than a paragraph of instructions. Extension guide.

MCP, the Model Context Protocol, connects tools and data from external programs through local servers or remote HTTP connections. Codemode lets the model compose tool calls in JavaScript, combining and filtering results before they return to the model. That can make related calls easier to manage; it cannot make an unsafe external operation safe. MCP guide and Codemode reference.

Packages share extensions, skills, prompts and themes through npm or Git. The package guide covers personal versus project installation and version pinning. For a shared setup, pin reviewed versions and record why each package is present. A long plugin list is harder to support than a workflow whose pieces have clear purposes.

Choose the model and follow the whole job’s cost

Pi supports multiple hosted providers, supported subscription logins and local or compatible endpoints. You can therefore choose the interface separately from the model. Models still differ in tool use, answer quality, context capacity and latency on the same task. Model selection.

Compare two models on the same files and task by the work they leave you. Did they find the right code, preserve its behavior and make the change easy to review? A model that handles routine documentation well might leave a difficult refactor expensive to check.

Local inference needs its own setup. The llama.cpp guide explains connecting to the router server and managing available models. The machine needs enough memory and suitable compute for the model and context. A terminal on your laptop does not make inference local: content in requests to a hosted provider still goes to that provider.

Pi itself is MIT-licensed, but a task can still have a bill. Hosted APIs may charge for input, output, cached context and other provider-specific usage. Subscription access has its own terms and limits. Local models trade that provider bill for hardware, power and maintenance rather than eliminating computation. Check the actual account instead of assuming every login has the same economics.

The closing message may be short after a long sequence of paid work. Another file adds context, a test adds output, and a repair adds another model turn. The token-usage guide follows that accumulation. Compare the completed job and effort, not the length of the last reply. Read /session, provider records and your own correction time together.

Return to an earlier conversation without losing track of files

A session tree lets you explore another approach without throwing away the first discussion. /tree returns to an earlier point; /fork starts separate work from an earlier message. Neither restores edited files. Use version control or separate working copies when those alternative conversations change the repository.

Resume the latest session for this directory with --continue, or choose one with /resume. Repeat tool and resource flags when continuing a restricted run; an old conversation does not preserve its old command line. Long sessions may be compacted into summaries for later requests while original entries remain saved. Important requirements belong in durable project files too, because a summary can lose a detail. Session guide.

A session export can explain how a result was reached, but it is a work log rather than a clean final report. It may contain prompts, file contents, command output and accidentally exposed credentials. Inspect it before sharing.

Limit what the whole Pi process can reach

Pi’s tools and extensions inherit the process’s permissions. The working directory is where work starts, not a fence around what it can reach. “Stay in this folder” cannot replace filesystem and network controls. Project trust decides which resources load, not which later actions are permitted. Pi security guidance.

For unfamiliar repositories or unattended work, isolate the whole process and expose only the required files and services. A container with the entire home directory and cloud credentials mounted inside retains much of the access you wanted to remove. Whole-process isolation includes extensions; isolating selected tools can leave other extension code on the host. Isolation choices.

Recheck the available tools after adding integrations. --tools read,grep,find,ls alone does not remove MCP tools. The first launch above also disables extensions, including built-in MCP. If external tools are later enabled, inspect their real permissions instead of assuming the old list still covers everything. CLI tool selection.

Keep exploratory analysis separate from production changes. A deployment, account update or other consequential action needs an allowed target, appropriate approval and a result checked at the destination. Pi can prepare a change; the operational process decides when and how to apply it. The OpenShell guide describes one way to place explicit controls around an agent.

Carry a useful interactive task into a script

When a reading task works interactively, print mode can put it into a script. For a prepared folder, this command writes the final response to standard output:

pi --no-approve --no-extensions --no-skills \
  --no-prompt-templates --no-context-files \
  --tools read,grep,find,ls --print \
  "Compare README.md with the project files. Report setup inconsistencies with file references."

Use the saved default model, or select the same model explicitly for repeated evaluations. Save the exit status with the report: print-mode errors, aborted responses and output-token cutoffs return a nonzero status. A cutoff can still leave partial text on standard output, so the presence of a report file is not enough.

JSON mode emits events, not a promise that the final answer follows your preferred JSON schema. A failed assistant response alone does not make that mode exit nonzero, so inspect the events. RPC keeps a process available for commands; acceptance of a prompt is not completion. Wait for agent_settled when automatic work must finish. The CLI integration explains these distinct contracts.

Use the SDK when an application needs direct programmatic control rather than increasingly elaborate shell parsing. Pi’s site points to OpenClaw as an integration example. It shows how a broader product can use the agent machinery, not that installing Pi supplies OpenClaw’s messaging channels or personal-assistant features.

Finish the small job before enlarging the assistant

Begin with work you already know how to judge: a small bug and its regression test, a request path through unfamiliar code, or documentation compared with the files it describes. Keep the first setup understandable enough to explain the result it produced.

Let the next repeated annoyance select the addition. A familiar question suggests a template. A procedure with references suggests a skill. A missing operation may call for code or a connected service. That leaves every part with a job someone else can understand.

You do not have to decide on the first day how elaborate Pi should become. Start with the utility, or another piece of work whose finish you can recognize. Keep the control that helps and add the capability you actually miss. The afternoon can end with milliseconds parsed correctly, without acquiring a second job maintaining the assistant.

Documentation was reviewed on October 14, 2026. The prompts, parser and data examples are constructed teaching material. Pi was not installed or run for this guide; no model performance, provider cost or production outcome was measured. The Python reference example was checked separately from Pi.