UFO

Pi, the coding agent

Short answer: Pi is a small, open-source terminal coding agent that ships with four tools and expects you to build the rest. That is not a gap in the product — it is the product. If you want sub-agents, plan mode, permission prompts and MCP out of the box, Pi has none of them and is not planning to, and you will be happier elsewhere.

It is also, by usage, one of the busiest coding agents nobody has written about. So this is the boring version: what it is, how to install it, what it can reach on your machine, and where the sharp edges are.

Written 2026-07-31 · Checked against pi v0.83.0, published 2026-07-29 · Figures read from vendor pages and the npm registry that day

On this page

  1. What Pi actually is
  2. What "yours" means concretely
  3. Installing it
  4. Models and the free path
  5. What it can touch on your machine
  6. What it deliberately doesn't do
  7. Oh My Pi, the fork
  8. Who it's for

What Pi actually is

Pi is a command-line coding agent published as @earendil-works/pi-coding-agent and run as pi. MIT-licensed, TypeScript, maintained by Earendil Inc. and contributors. The repository began as badlogic/pi-mono under Mario Zechner and now lives at earendil-works/pi; the old npm package under the @mariozechner scope stopped at 0.73.1 on 2026-05-07 with the note "please use @earendil-works/pi-coding-agent instead going forward."

The scale is why this page exists. On 2026-07-31 the repository has 81,050 stars, the npm package recorded 5,749,783 downloads in the preceding 30 days, and its OpenRouter listing shows 2.27T total tokens and rank #5 in both Coding Agents and CLI Agents, active since February 2026 across 323 models. Almost none of that has produced documentation written by anyone outside the project.

Its OpenRouter tagline is the line most people will have seen:

There are many coding agents, but this one is yours.

On its own site it reads "many agent harnesses" instead, under a plainer description: "Pi is a minimal agent harness. Adapt Pi to your workflows, not the other way around."

Name collisions to clear first. Not Inflection's Pi assistant, not Raspberry Pi, and not the unrelated pi-coding-agent package on PyPI. This one is the npm package under the @earendil-works scope, homed at pi.dev.

What "yours" means concretely

In most tools "personalisation" means a settings page. Here it is more literal. Out of the box the docs state plainly: "By default, pi gives the model four tools" — read, write, edit, bash. Three read-only tools (grep, find, ls) sit behind tool options. That is the whole surface.

Everything above that line is an extension: a TypeScript module loaded from ~/.pi/agent/extensions/ or a project's .pi/extensions/, run through jiti so there is no build step. It is not a thin plugin hook — extensions register tools, commands, keyboard shortcuts, flags and custom TUI renderers, and intercept events. One can return { block: true, reason: "…" } from a tool_call handler and stop a command outright, which is how you would build a permission gate.

What makes the tagline more than marketing is /reload. Extensions in auto-discovered locations hot-reload, so the documented workflow is to ask Pi to modify its own extension, reload, and keep the session going: "If you need a command, tool, provider, workflow, or UI tweak, just ask Pi to build it."

Alongside sit skills loaded on demand, prompt templates, themes, and Pi packages bundling all of it from npm or git. Context is steered by AGENTS.md (or CLAUDE.md) plus a per-project SYSTEM.md that replaces or appends to the system prompt. So the claim is real — but conditional. If you do not write TypeScript, the honest version of "yours" is "someone else's package, or whatever Pi manages to write for you."

Installing it

The published paths, all from the project's own pages as of 2026-07-31.

curl -fsSL https://pi.dev/install.sh | sh

Windows, in PowerShell:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Or through a package manager — note the flag, which the project uses in its own instructions:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
bun add -g --ignore-scripts @earendil-works/pi-coding-agent

The docs explain it as "--ignore-scripts disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs." The package requires Node ≥ 22.19.0 — a floor that lives in the package metadata rather than the quickstart, so it is easy to miss until the install fails. Then run pi in a project directory.

First commands worth knowing: /login for auth, /model or Ctrl+L to switch model mid-session, ! to run a shell command and feed its output to the model, @ to fuzzy-search files into the prompt. Sessions auto-save to ~/.pi/agent/sessions/ as JSONL trees; pi -c continues the last, /tree navigates back to any earlier point, /fork branches, /share uploads a rendered session as a gist. Uninstalling leaves all of that behind — "settings, credentials, sessions, and installed pi packages" stay in ~/.pi/agent/.

Models and the free path

Pi is bring-your-own-model in the fullest sense: no Pi subscription, no hosted inference, no license key. Cost is whatever your provider charges.

Two ways in. /login handles subscriptions — as of 2026-07-31 the docs list ChatGPT Plus/Pro (Codex), Claude Pro/Max, GitHub Copilot, xAI, OpenRouter and Radius. Everything else is an API key, set as an environment variable or stored in ~/.pi/agent/auth.json; the providers table lists more than thirty, including Anthropic, OpenAI, Gemini, Bedrock, Vertex, Azure, Mistral, Groq, Cerebras, DeepSeek, MiniMax, Qwen and llama.cpp. Resolution order is --api-key, then auth.json, then the environment variable — the file beats your shell, which catches out anyone chasing a stale key.

The Claude subscription detail that costs money if you miss it. Signing in with Claude Pro/Max works, but the docs are explicit about what you are spending: "Third-party harness usage draws from extra usage and is billed per token, not against Claude plan limits." It is not the free ride the /login menu implies. Codex and Copilot are listed without that caveat.

There is a genuinely free path, with conditions. pi-freerouter is a third-party package — by parkjangwon, MIT, requiring pi 0.78+ — that routes to OpenRouter's free-tier models. Its own page is candid: free models are rate-limited to "typically a few requests per minute per model", and it "sends your prompt, conversation context, and enabled tool definitions to OpenRouter and the selected free model provider", with advice against using it for secrets, credentials, private source code or regulated data.

What it can touch on your machine

Pi's security documentation is unusually direct, and reading it is not optional. It runs as you, and there is no sandbox.

Pi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process. Extensions are TypeScript modules that run with the same permissions.

That is a design position, not an oversight: the docs argue "real isolation needs to come from the operating system or a virtualization/container boundary", and that a partial in-process sandbox "would be easy to misunderstand as a security boundary." For untrusted repositories or unattended runs, the recommendation is a container, a VM, or routing tool execution into the Gondolin micro-VM.

There is a project trust prompt, and it is narrower than it looks. It gates whether Pi loads project-local configuration — .pi/settings.json, .pi/extensions, .pi/skills, .pi/SYSTEM.md and friends — so a cloned repository cannot silently rewrite your agent before you approve it. The docs draw the line themselves: it "is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory." AGENTS.md and CLAUDE.md load regardless of the decision, and -p, --mode json and --mode rpc never prompt at all.

The same caution applies to the ecosystem that makes Pi appealing: "Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables."

What it deliberately doesn't do

The project keeps a public list of features it declined to build, each with the workaround it expects instead. As of 2026-07-31:

Not built inWhat the project suggests instead
MCPCLI tools with READMEs, exposed as skills — or an extension that adds MCP
Sub-agentsSpawn Pi instances via tmux, build one with extensions, or install a package
Permission popupsRun in a container, or build your own confirmation flow as an extension
Plan modeWrite plans to files, or build it with extensions
Built-in to-dosA TODO.md file
Background bashtmux — "Full observability, direct interaction"

Whether that reads as principled or as homework depends on you. "Build it yourself" costs real hours, and a team standardising on one agent usually wants the opposite bargain. If sub-agents are what you came for, the cost model there is not intuitive and is worth understanding first.

One thing Pi has that many agents do not: four run modes — interactive TUI, print/JSON for scripting, RPC over stdin/stdout, and an embeddable SDK. OpenClaw is cited by the project as a real integration built on that SDK, which is a better signal than a feature list.

Oh My Pi, the fork

Searching for Pi will surface Oh My Pi (omp), and the relationship is settled rather than ambiguous. Its README states it directly: "Fork of Pi by @mariozechner." It is a separate project by can1357, MIT, started 2025-12-31, at 20,785 stars on 2026-07-31 — and it inverts Pi's bet, adding a Rust core, LSP and DAP integration, subagents, plan mode and a much larger tool set, describing itself as "complete out of the box."

They are not interchangeable installs. Pi is @earendil-works/pi-coding-agent, run as pi; omp is @oh-my-pi/pi-coding-agent, run as omp, from omp.sh. Their OpenRouter listings are separate, and on 2026-07-31 the gap is wide: 2.27T total tokens against 433M, and 1.54M npm downloads in the last recorded week against 78,331. If Pi's minimalism is what you want, use Pi; if you liked the idea but wanted the batteries, the fork exists for exactly that.

Who it's for

Pi fits if you have opinions about your harness and resent tools that impose theirs — if you would rather write forty lines of TypeScript than accept someone's approval dialog. It fits badly if you want defaults good enough to never touch, if you need a permission boundary the tool enforces rather than one you build, or if you are equipping a team that will not maintain extensions. Pi's own docs will tell you it does not meet those.

Where we fit, briefly

We build UFO, so weigh this accordingly — and the answer to "should I install Pi" is not us. That question is settled above, by Pi's own docs.

UFO is the layer after a single terminal agent: a team chat where AI agents are members of channels alongside people, each on a machine you have paired, with task cards for work that outlives a session. Pi is a thing you would run inside that.

Sources

All of this comes from the project's own site, docs and repository, plus the npm registry and OpenRouter's app listing, read on 2026-07-31 against pi v0.83.0. Counts move daily.

Not affiliated with Earendil Inc. or the Pi project. If something here is wrong or has gone stale, tell us and we'll fix it.