Build Your Own AI Agent With pi, Explained In 11 Minutes

Claude Code, Codex, and Gemini CLI are agent harnesses that someone else designed — and if you spend your working day inside one, you live with that design. Want to change one behavior, add a tool, or tighten a permission rule? You wait for the vendor to ship it. You don't know what's in the system prompt, you can't see the loop that runs the tools, and you can't change any of it, even though these tools have become the main workstation for thousands of developers.

One open source project takes the opposite approach: pi, a toolkit that ships the spare parts to assemble your own agent, from the model connector all the way to the interface. It earned 92,000 GitHub stars in its first year and ships a release roughly every week. This article covers what pi actually puts in the box, how to build your own agent with its SDK, and an honest verdict against the ready-made harnesses.

A harness is all the machinery around a language model that turns it into a working agent. A model on its own can only read text and produce text: it doesn't read your files, it doesn't run a single command, and it remembers nothing between sessions. Everything else is the harness — the system prompt that frames the model, the tools exposed to it, the loop that executes tool calls and feeds results back, and the interface in your terminal.

The harness also decides the details that matter day to day: how history gets compacted when the context overflows, how a tool error is reported back to the model, what gets logged and what doesn't. Claude Code is a harness. Codex is one too. When an agent impresses you, a good share of the credit belongs to that machinery rather than the model — plug the same model into two different harnesses and you get two agents that are not on the same level.

pi, built by Earendil Works, cuts that machinery into reusable bricks. You can use its coding agent as-is, or take the bricks one by one and build your own. The second option is the interesting one.

pi is a monorepo — one repository hosting five separately published packages — and each package covers one floor of the harness:

Package	What it does
pi-ai	Unified API over OpenAI, Anthropic, Google and the rest: response streaming, reasoning blocks with thinking levels, dynamic discovery of each provider's models. Switch labs by changing an argument.
pi-agent-core	The agent loop itself: conversation state, plus the cycle that sends the message, reads the tool calls, runs them, and returns results until the task is done. The twisted cases — a failing tool, a cut-off response, parallel calls — are already handled.
pi-tui	Terminal rendering library with differential rendering: it only redraws what changes on screen.
pi-coding-agent	The complete coding agent assembled from the bricks above — proof by example that the toolkit is enough to build a finished product.
pi-telemetry	Plug in your own usage metrics without depending on a vendor.

The agent loop is exactly the piece you would rewrite badly from scratch; writing it properly is weeks of work you get back in one import. The team applies the same recipe elsewhere: a separate repository, pi-chat, reuses the same bricks for conversation automation.

The numbers say the formula works:

Metric	Value
GitHub stars	92,123
Forks	11,400
Commits	5,700+
License	MIT
Releases in the first two weeks of August 2026	3 (v0.84.2 shipped August 14)

The MIT license means you can use, modify and redistribute pi without restriction, including in a commercial product. pi is not yet another framework: it's a complete harness delivered in spare parts, maintained at a steady clip.

The pi CLI is the assembled coding agent you get before touching any code, and it's where you'll start. The install is one line, and its --ignore-scripts flag is not a detail: it stops your dependencies from running their install scripts, one of the most abused attack surfaces on npm. Launch pi, connect your provider with the login command, and you have a coding agent in your terminal. The status bar shows the current folder, the session, the tokens burned and the cost in real time — so you see every request priced the moment it leaves, instead of discovering the bill at the end of the month.

Slash commands cover the day-to-day: model to switch models mid-run, compact to summarize history when the context swells, export to pull the conversation out, settings for the rest. A markdown file dropped in the prompts folder becomes a command you trigger by typing its name.

pi's real signature is session handling. Every conversation is saved as JSONL in your home folder, sorted by project — and the history is a tree, not a line. You can return to any point of a conversation and head another way with fork, then move between branches with tree. A failed prompt costs nothing: go back to the node before it and try again without losing the previous branch. Since everything is stored locally, resume drops you back into any past session, even weeks later. Neither Claude Code nor Codex offers history navigation in this form.

By default the model gets only four tools: read, write, edit and bash. That is very little next to the agents on the market, and it's deliberate (more on that below). Configuration follows the same logic: a global settings file in your home folder, a per-project file that overrides it, and a trust system that asks before applying the local settings of a folder you open for the first time. If you migrate, pi automatically loads your project's AGENTS.md or CLAUDE.md files as context, so existing instructions work without a rewrite.

Building an agent with pi's SDK starts with one import: createAgentSession, handed a model runtime and a session manager, returns a working agent. The session manager is the persistence choice — in memory for a throwaway script, or on disk to keep conversations between runs.

We tried it on a local project. Our script asks what's in the current folder; the agent calls its read tool, reads the directory, and answers. That is the full loop, written by us, in about ten lines of TypeScript. Sessions created by the SDK have the same tree structure as the CLI's — every message is linked to its parent — so history branching works inside your own code too.

Custom tools are where it gets interesting. defineTool takes a name, a description, a typed parameter schema and an execute function, and your tool appears to the model exactly like read or bash. We wrote one that queries the channel's video list, passed it in customTools, and the agent called it on its own from the first relevant question. It's essentially the same mechanism as an MCP server, except everything lives in your file — no separate process, no protocol in between. Because the parameter schema is typed, your editor autocompletes the arguments and the agent receives inputs that are already validated.

You also control the model, the thinking level (from fully off up to max), the exact list of tools the model sees, and even the whole system prompt through a resource loader if you want to start from a blank page. For display, session.subscribe hands you every event — streamed text, tool calls, errors — to redirect wherever you want: a terminal, a messaging bot, or a CI pipeline that comments on your pull requests. In one afternoon you go from using an agent to having written one, and you finally know what happens on every turn of the loop.

pi's CLI is customized through four mechanisms, all sitting in plain folders in your project or your home directory:

• Extensions — TypeScript modules that register tools, slash commands, keyboard shortcuts or UI elements. Drop the file in the extensions folder and it loads on launch. This is where you'd write a permission guard, for instance: an extension that intercepts bash commands and asks for confirmation before the dangerous ones.
• Skills — capability packages following the Agent Skills standard, the same one Anthropic popularized, so existing skills are reusable as they are.
• Prompts — reusable prompts as plain markdown files.
• Themes — hot-reload while the CLI runs.

All of it ships like any package: pi install takes an npm package or a git repository, and one command updates everything. The docs sum up the philosophy in one sentence: adapt pi to your workflows, not the other way around, without forking or patching the internals.

It's the reverse of the big harnesses. Where Claude Code ships sub-agents, plan mode and permissions inside the product, pi deliberately leaves them out, to be built as extensions or installed from the community. The bet is clear: a minimal core that barely moves, and all the customization living on your side, in files you version with your project.

pi's transparency is paid for in work, and that cost comes in three parts.

Guardrails first: by default there are no built-in permission prompts, so the agent can run a bash command without asking anything. The official docs own this and propose three isolation patterns, Docker included — but putting them in place before you let the agent loose on a machine that matters is on you.

Then maturity: this is v0.84, not 1.0, with about a hundred open issues and some APIs still flagged experimental, like the remote session client added in recent weeks. What works today can break on next week's release; that is the normal price of a project moving this fast.

Finally, time. Every comfort Claude Code gives you out of the box — plan mode, sub-agents, fine-grained permissions — is a project you build yourself here, or a community package you hunt down and hope stays maintained. The extension ecosystem is a year old: you'll find fewer ready-made packages than holes to fill. Even the install taught you the level of vigilance this takes, with its --ignore-scripts flag, and you'll have to hold that level across the whole chain. If your goal is shipping code tonight, pi will slow you down before it speeds you up — don't replace your main harness this week.

pi is for developers who build products with agents, not just with one agent. For them it's probably the best learning investment around right now: install the CLI, write a twenty-line agent with the SDK, and give it one tool of your own. Do that and you'll understand what Claude Code does better than most of its users.

If all you want is a productive assistant today, keep your integrated harness and come back when the 1.0 has shipped the guardrails: pi's value is in understanding and control, not in immediate comfort. Between the two sits a risk-free middle ground — keep Claude Code for your work, and pi as a test bench to understand what your main tool hides from you.

The takeaway: harnesses aren't black boxes anymore. The parts are on the table, documented, MIT licensed. The next time an agent impresses you or annoys you, you'll know exactly which part to look at.