Meet Pi — the Terminal Agent That's Yours

Lesson 1: Meet Pi — the Terminal Agent That's Yours

Pi is a terminal-based coding agent: a program that sits in your shell, reads your repository, and uses an LLM plus a small set of tools (read, write, edit, bash) to do software work. It is a harness, not a model — it doesn't contain intelligence, it wires intelligence to your filesystem. The marketing line on pi.dev says it best: "There are many agent harnesses, but this one is yours."

Key idea: A harness is everything around the model: the tool loop, session storage, prompt construction, compaction, extensions. Pi's philosophy is a minimal, predictable core that you extend in TypeScript instead of a giant monolithic product.

Where pi came from

Pi was created by Mario Zechner (better known as badlogic, the creator of the libGDX game framework). It started as the open-source pi-mono repository and is now maintained by Earendil Inc. as the @earendil-works/pi-coding-agent npm package. It's MIT-licensed, and its docs, news, model catalog, and package gallery all live at pi.dev. Mario's talks — "Building pi in a World of Slop" and "I Hated Every Coding Agent, So I Built My Own" — are the definitive design philosophy statements.

Installing and running

# npm (also used by the curl installer)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# then, in your project
cd /path/to/project
pi

On first launch you authenticate: /login supports subscription providers (Claude Pro/Max, ChatGPT Plus/Pro via Codex, GitHub Copilot), or you can set an API key via environment variable (e.g. ANTHROPIC_API_KEY) or store it in ~/.pi/agent/auth.json. By default the agent gets four tools: read, write, edit, and bash. Read-only helpers like grep, find, and ls are available through tool options.

The four areas of the TUI

1 · startup header — shortcuts, skills, templates, extensions 2 · messages — user, assistant, tool calls/results notifications, errors, extension UI 3 · editor — border color shows thinking level 4 · footer — cwd · session · tokens/cache · cost · context % · model

The footer is where the economics live: it shows token and prompt-cache usage, running cost, context-window usage, and the active model. This is the single most important thing to glance at when you start a long session.

🪙 Token angle: Pi's footer turns your token spend into a live dashboard — watch the cost and cache columns, not just the context bar. Your choice of authentication also shapes the budget: subscription logins (Claude Pro, Codex, Copilot) are flat-rate, while API keys meter per token. If you're cost-sensitive, that choice matters more than any prompt trick.

Project context

Pi loads context files at startup — AGENTS.md and similar — so the model starts with your repo's conventions. You can also give it one-off project instructions interactively. Everything is saved as a session (a JSONL tree) so you can resume, branch, and revisit later turns — the topic of Lesson 2.

📺 Watch before continuing:

Further Reading

🧠 Knowledge Check

1. What is pi, fundamentally?

2. Which four tools does pi give the model by default?

3. What does the TUI footer show that is directly relevant to token spending?