Pi Coding Agent

Pi gives you control over the agent around your model

Pi is a minimal agent harness, the software that connects a model to your files and commands. Think of it as the workbench: your chosen model decides what to do, and Pi gives it the equipment to do it.

Its four default built-in tools cover the core loop:

The model requests a tool, Pi executes it, and the result goes back into the conversation. That can repeat until the task finishes. These are the four tools enabled by default, rather than an exhaustive list of every built-in tool available in 1.0. Pi tool reference, agent loop.

If you already use Claude Code or Codex, evaluate Pi by the workflow you want to own. My recommendation: try it when you have a specific customization in mind, such as a repository review command or a reusable migration skill. For a broader shortlist, see model-agnostic coding agents.

Pi 1.0 changes the terminal experience and tool plumbing

The 1.0.0 release makes fullscreen the default and refines codemode and sign-in. A TUI is the interface drawn inside your terminal; these are the changes that matter during setup:

MCP connects the agent to external tools. OAuth is the sign-in flow that grants access without giving the tool your password. Codemode lets the model compose tool calls in JavaScript and return selected results to the conversation. Its prompt reduction applies to that setup; it is not a promise of a 40% smaller bill for every task. Pi 1.0.0 release notes, codemode reference.

The same release adds image generation from codemode scripts, Radius in /login, and quietStartup: "header". You can leave those features aside for the first coding task. Release notes.

Set up Pi and finish a first task in a 28-minute budget

Start with a repository you know, a working test command and access to a supported model. The timing below is a suggested budget; downloads, sign-in and test duration depend on your environment. Pick a task small enough to review before the session ends.

Minutes 0 to 5: install and open your project

The project's npm route requires Node.js 22.19 or newer. This command pins Pi to 1.0.0 so your walkthrough matches the release covered here:

node --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.0.0
pi --version
cd /path/to/project
pi --tui-mode regular

Replace /path/to/project with your working folder. pi --version should report 1.0.0. Running plain pi uses the new fullscreen default. The official macOS/Linux alternative is curl -fsSL https://pi.dev/install.sh | sh, which installs the current release. Project installation docs, quickstart.

Minutes 5 to 10: connect the account you already have

Run /login inside Pi, choose your provider and complete the offered authentication method. Then run /model and choose an available model. A provider is your access route; a model is the system generating the responses.

Pi's own authentication documentation lists the Anthropic subscription and OpenAI Sign in with ChatGPT routes. OpenAI describes plan usage as an authorization for eligible requests, subject to account eligibility. Choosing an API key is a separate billing path. Pi OAuth providers, OpenAI sign-in documentation.

The Pi website lists Anthropic, OpenAI, Google, OpenRouter, Ollama and more. Provider support does not make every model appear in every account. If a model is missing, check authentication first; /model shows models with usable credentials. Press Ctrl+S in the picker to save your default. Model selection docs.

For Ollama, follow the project's compatible-endpoint example in ~/.pi/agent/models.json: it uses http://localhost:11434/v1, API type openai-completions, dummy key ollama, and a model ID served by your installation. Opening /model reloads that file. This is the local route if you want to try Pi without a paid model account.

Minutes 10 to 13: give Pi repository instructions

Add a short AGENTS.md at the repository root, or extend the one you already maintain. Pi discovers instructions from ~/.pi/agent/, parent directories and the current directory. Run /reload if you change them during a session. Configuration docs.

Use instructions that describe your actual repository. For example:

Use the existing test runner and neighboring test conventions.
Keep this task within the function and tests I name.
Do not add dependencies or change the public API.
Run the focused tests and report the exact command and result.
Leave commits and publishing to me.

Add the real focused-test command if you know it. AGENTS.md guides the model; it does not enforce a permission boundary.

Minutes 13 to 23: make one useful change

Choose an existing helper whose empty-input behavior is defined but lacks a regression test. Attach that helper and a neighboring test with @, Pi's file picker, then give it this task:

A regression test protects an expected behavior from breaking later. This task produces a concrete diff without requiring Pi to redesign your application. The quickstart documents @ file selection and reviewing changed files after a task. First-task docs.

Minutes 23 to 28: review the evidence

Read the changed test and inspect git diff, the list of file changes. Confirm that its assertion checks the expected behavior, then run the focused test command yourself. Passing tests support the change; you still decide whether the assertion is useful and the scope is right.

Your first-run finish line is simple: the chosen provider worked, Pi made the intended change, and you can explain the diff. Save customization work for the next session.

Pi is free software; model usage determines the bill

Pi's MIT license adds no software seat charge. Subscription access consumes the access supplied by that plan; an API key produces the provider's usage bill. A local model shifts the expense to your hardware and operation.

For a worked API example, OpenAI prices GPT-6.1 Sol standard short-context usage at $2 per million input tokens and $10 per million output tokens. Tokens are the pieces of content counted for billing. Official OpenAI pricing.

Suppose a small task accumulates the following usage across its requests:

This is illustrative arithmetic, not measured task usage. It assumes standard processing, each request at or below 272,000 input tokens, and no cache writes or separately charged tools. Cached input, cache writes, longer requests and other processing tiers have different rates. One hundred tasks with exactly that usage pattern would cost $30 in base model charges. GPT-6.1 Sol pricing details.

The budget decision is whether the customization you want justifies maintaining it. Pi removes a harness license fee; it does not remove model spend, human review or the engineering time required to support your workflow.

Extend the workflow with the smallest useful mechanism

Use instructions for conventions, skills for repeatable procedures and extensions for executable behavior.

A skill's SKILL.md starts with a name and description. Invoke a particular skill with /skill:name when you want it loaded explicitly. Extensions run inside Pi's process, so review their code before loading them. Skills, extensions.

pi install ./local-package installs a package you have prepared locally. For a published package, use pi install npm:@scope/package@version with its actual name and version. Add --local to record a project-level package declaration in .pi/settings.json. Run /reload after changing resources in an active session. Package docs.

For an external MCP service, configure its server and use /mcp login <server> when OAuth is required. Treat that as a later addition to a working setup. MCP documentation.

Six useful jobs, ranked by practical payoff

The strongest starting point is recurring work in a repository you understand. These are proposed workflows, with the payoff depending on your codebase and review discipline.

1. Add regression coverage around a reported bug. A founder maintaining a subscription web app could attach the bug reproduction, implementation and tests, ask Pi for a failing test and a focused fix, then rerun the relevant checks. The value is carrying the observed failure into a permanent test.
2. Review a change before opening a pull request. A developer could give Pi a local diff and a repository review skill, requesting potential defects with file references and an explanation. Catching a concrete issue before review could reduce a round of back-and-forth.
3. Migrate one bounded part of an application. A maintainer could encode the migration procedure as a skill, apply it to one module and run its checks. The potential saving comes from reusing the procedure across similar modules while reviewing each diff.
4. Explain an unfamiliar repository. A new engineer could ask Pi to trace one request from entry point to storage, then save notes with file references and the relevant check commands. Those notes could reduce repeated setup questions.
5. Write a small maintenance script. An operator responsible for stale fixtures could have Pi draft a script, exercise it on sample inputs and document usage. A reviewed script could replace repeated manual edits.
6. Build an internal developer workflow. A technical lead could package a custom command and skills, or integrate Pi through print mode for one-off commands, RPC to control a separate process, or the SDK library to embed sessions in an application. The payoff is fitting the agent to a recurring job; the lead owns integration and support. Integration interfaces.

The strongest build opportunity is a repository-specific reviewer

A pre-merge review package is the clearest opportunity because the job repeats and the buyer already knows the cost of review delays. A small engineering team could pay for a maintained package that checks its own conventions and produces evidence for reviewers.

The demand check returned 1,300 estimated monthly US Google searches for “ai code review”. CodeRabbit Essentials provides a price anchor at $24 per developer per month billed annually, or $30 billed monthly. These indicate interest in the job and an existing paid category; they do not establish demand for a Pi package. Search volume: DataForSEO keyword overview, checked 3 October 2026. CodeRabbit pricing.

The smallest sellable version could include a review skill, a command that gathers the local diff, repository-specific checks and a report with file references. Keep delivery local initially. The catch is differentiation: a generic prompt is easy to copy, and a Pi package needs its own maintenance, access controls and support. Sell the quality of the repository checks and their upkeep.

A team starter package is the second opportunity. An engineering lead could buy setup and maintenance for a consistent provider configuration, AGENTS.md, shared skills and a small approved extension set. The demand check returned 1,600 estimated monthly US searches for “open source ai coding assistant”, measured by DataForSEO on the same date. The first version could be one package plus an onboarding procedure for one team's repositories. The catch is that search interest does not prove willingness to pay for installation; the ongoing value must come from maintaining the team's workflow.

Pi is the wrong pick when nobody wants to own the defaults

Choose a managed tool if your team expects permission gates, isolation and standardized workflows to arrive as a supported product. Pi's tools use the permissions of the process that starts it. Project trust controls which project resources load, but it does not sandbox tool calls. A working folder does not prevent commands from reaching other accessible paths. Pi security model.

Extensions can add confirmation flows or path protection, and a container can provide an operating-system boundary. Those choices create implementation and maintenance work for your team. Codemode's JavaScript sandbox also leaves the called tools' permissions intact. Extension capabilities, codemode.

Pi also leaves built-in sub-agents and plan mode out of its core. My judgment: this is a good trade for a developer who wants a small base to shape, and a poor trade for a team that wants someone else to own those decisions. Project design choices.

On Monday, give Pi one bounded bug or test task in a repository you maintain. Keep the diff and test result, then decide which recurring procedure deserves a skill. If you want a custom workflow built for your team, AI agent development is where to start.