π Pi, Explained
Home / Chapter 1

Meet Pi — the coding agent that packs light

Easy What Pi is, why it's interesting, and how to get it running in about a minute.

The 30-second version: Pi is a coding agent that lives in your terminal, keeps its core almost embarrassingly small, and assumes you might want to reshape it. It ships with four tools, a tiny system prompt, and a big philosophy: whatever's missing, you can build yourself.

So, what is a coding agent anyway?

If you've never used one, here's the pitch: you open a terminal in your project, describe what you want in plain English (or Chinese!), and a large language model starts doing things — reading your files, editing code, running commands, checking the results, and trying again until it's done.

It's less "chatbot" and more "a very fast intern who never gets tired of reading source code."

Pi is one of these. The official description calls it "a minimal terminal coding harness" — and every word there is doing real work:

  • minimal — it deliberately ships with less than its competitors
  • terminal — no GUI, no IDE plugin. It lives where your shell lives
  • harness — it's not just an app; it's a frame you can bolt your own parts onto

The unusual bet: less is more

Most coding agents compete on features. Plan mode! Sub-agents! Permission popups! Built-in task lists! Pi reads that list and says "no thanks" — then publishes an actual section of its website about what it chose not to build.

Why would anyone do that? Pi's answer has three parts:

1. Context is precious. Everything baked into an agent — tool descriptions, system instructions, feature machinery — eats tokens from the same window your code has to fit in. Pi's four default tools (read, write, edit, bash) plus its system prompt fit in roughly a thousand tokens. That's room returned to your actual work.

2. Built-in features are frozen decisions. A feature you can't turn off is a decision someone else made for you. Pi would rather hand you the ingredients: TypeScript extensions, skills, prompt templates, themes, and shareable pi packages. Don't like how something works? Change it. Missing something? Build it — or install someone's build.

3. Small things are readable. Pi's core is small enough that one person can actually read it. Which is exactly why it doubles as a textbook on agent design — and why this site exists.

Think of it this way: some agents sell you a car. Pi sells you an engine, a chassis, and a very good manual — plus a workshop.

The five packages (one picture)

Under the hood, the project is a monorepo. Three packages form a stack, and each layer works on its own:

pi-coding-agent      the full CLI product — and the SDK
       ▲
pi-agent-core        the agent runtime: the loop, tools, state, events
       ▲
pi-ai                one API to call 30+ LLM providers

pi-tui               a terminal UI library, happily independent of all the above

Want to call models with one unified API? Take pi-ai and leave. Want to run your own agent with your own tools? Take pi-agent-core too. Want the whole coding assistant? That's pi-coding-agent. And pi-tui — the terminal rendering engine — depends on none of them; it's a standalone library that happens to share an author with the rest.

We'll meet each of these as we go. For now, just remember the shape of the stack.

Let's actually run it

Enough philosophy. Install:

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

(On Linux/macOS there's also curl -fsSL https://pi.dev/install.sh | sh. The --ignore-scripts flag is a supply-chain hygiene habit Pi itself recommends — it doesn't need install scripts.)

Then, in any project directory:

cd your-project
pi

Authenticate once — either /login inside Pi (works with Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot subscriptions) or a plain API key like ANTHROPIC_API_KEY.

And… that's it. Type a request:

Summarize this repository and tell me how to run its checks.

Pi will start reading files, thinking, and answering. Congratulations — you're now watching an agent loop run. We'll see exactly how it works in the next chapter.

Five tricks worth knowing on day one

These come straight from the official quickstart, and they make Pi feel nice immediately:

Reference files with @. Type @ in the input box and fuzzy-search your project, or pass files on the command line:

pi @src/app.ts @src/app.test.ts "Review these together"

Run shell commands with !. One bang runs a command and shows the output to the model. Two bangs run it quietly — output stays out of the model's context:

!npm run lint      ← the model sees the result
!!npm run build    ← the model never sees the noise

Switch models mid-conversation. /model (or Ctrl+L) opens a fuzzy picker. Shift+Tab cycles thinking levels. If your provider bill is watching, this is your best friend.

Sessions save themselves. Close the terminal, come back tomorrow, run pi -c to continue exactly where you left off. pi -r browses old sessions.

One-shot mode for scripts. No interactive session needed:

pi -p "Summarize this codebase"
cat error.log | pi -p "What's going wrong here?"

Teach it your project's rules

Here's a small feature with outsized impact: Pi reads context files at startup. Drop an AGENTS.md in your project root:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Pi picks it up (and walks up the directory tree collecting more, plus a global one at ~/.pi/agent/AGENTS.md). Changed it while Pi was running? /reload.

This is the first glimpse of Pi's whole worldview: don't hard-code behavior into the tool — write it down, and let the tool read it. Skills, extensions, and prompt templates all extend the same idea.

What's next

You now know what Pi is and how to start it. But typing a prompt and getting an answer hides the interesting part: the loop — the mechanism that lets a model keep thinking, acting, and observing until the job is really done.

That's next. →

Sources & further reading: pi.dev · official docs · earendil-works/pi on GitHub