pi agent toolkit: five packages, SDK recipe, verdict table and Monday checklist

TL;DR

• pi is an MIT-licensed monorepo that ships a coding agent harness as five separate packages: a model API layer, the agent loop, a terminal UI library, the coding agent itself and a telemetry package. You can take one brick or all five.
• The CLI is a complete coding agent on day one: four default tools, tree-shaped session history with fork and resume, a live cost counter, and it reads the AGENTS.md or CLAUDE.md already in your repo.
• The SDK side holds the real value: createAgentSession plus a model runtime plus a session manager gives a working agent in about ten lines of TypeScript, and defineTool adds a typed custom tool without a separate process or protocol.
• The cost of that transparency is work: no built-in permission prompts, isolation left to you, a pre-1.0 version line (v0.84) and roughly a hundred open issues.
• Keep your daily harness, use pi as the test bench that shows you what that harness hides. Build products on it only if you accept to own the guardrails.

What the sources say

pi is a monorepo: one repository hosting five packages published separately, each covering one layer of the harness s2. pi-ai is the unified API toward model providers (OpenAI, Anthropic, Google and others behind one interface), handling response streaming, reasoning blocks with their thinking levels and dynamic discovery of the models each provider offers s2. pi-agent-core is the agent loop itself: conversation state and the cycle that sends a message, reads the tool calls, executes them and feeds results back s2. pi-tui is a terminal rendering library with differential rendering, so it only redraws what changed on screen s2. pi-coding-agent assembles those bricks into the CLI you install, and pi-telemetry lets you wire your own usage metrics without depending on a vendor s3.

The adoption numbers back the design: 92 123 stars, 11 400 forks and more than 5 700 commits, all under the MIT license, which allows use, modification and redistribution including inside a commercial product s1. The release cadence held through the summer: three releases over the first two weeks of August, with v0.84.2 published on the 14th s4.

Installation is one command, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, and the ignore-scripts flag matters: it stops dependencies from running their install scripts, one of the most used attack surfaces on npm s3. Once connected to a provider through the login command, the bottom bar shows the current folder, the session, tokens consumed and the cost in real time, so every request is priced as it leaves instead of at the end of the month s3.

Sessions are the distinctive feature. Every conversation is saved as JSONL in your home folder, sorted by project, and the history is a tree rather than a line: fork returns to any point and branches off, tree navigates between branches, and resume reopens any past session, weeks later, because everything is stored locally s3. The model receives only four tools by default: read, write, edit and bash, very few compared with the agents on the market, and deliberately so s3. Configuration follows the same logic: a global settings.json in your home, a per-project one that overrides it, and a trust system that asks before applying the local settings of a folder you open for the first time. The CLI also loads the AGENTS.md or CLAUDE.md of your project as context, so existing instructions work without a rewrite s3.

On the SDK side, createAgentSession takes a ModelRuntime and a SessionManager and returns a functional agent. The SessionManager is the persistence choice: in memory for a throwaway script, on disk to find your conversations again across launches, and sessions created by the SDK share the structure of the CLI's own sessions s8. The options list of createAgentSession also lets you choose the exact set of tools exposed, and even the whole system prompt through a ResourceLoader when you want to start from a blank page s8. Custom tools go through defineTool: a name, a description, a typed parameter schema and an execute function, passed to createAgentSession in customTools. The tool appears to the model exactly like read or bash, the typed schema gives you editor autocompletion and the agent receives already validated inputs. It is the same mechanism as an MCP server, except everything lives in your file, without a separate process or a protocol in between s8.

The CLI itself is customized through four mechanisms, all placed in folders of your project or your home: extensions (TypeScript modules that register tools, slash commands, keyboard shortcuts or UI elements, loaded at startup from the extensions folder), skills (capability packages following the Agent Skills standard, invoked by the model or called by hand, so existing skills are reusable as they are), prompt templates, and themes reloaded while the CLI runs s3. The README states the philosophy in one line: adapt pi to your workflows rather than the reverse, without forking or touching the internals s3. Where the large harnesses bundle sub-agents, plan mode and permissions into the product, pi leaves them out on purpose, to be written as extensions or installed from the community s3.

The limits are documented by the project itself. There are no built-in permission prompts: by default the agent can run a bash command without asking. The official containerization guide owns this and proposes three isolation patterns, Docker among them, but setting one up before letting the agent loose on a machine that matters is your job s5. Maturity is the other cost: v0.84, not 1.0, around a hundred open issues, and APIs still marked experimental such as the remote session client added over the preceding weeks s7. The same bricks already serve another product: pi-chat applies them to conversation automation s6.

Verdict: keep, try or skip

Do this Monday

• Install the CLI with npm install -g --ignore-scripts @earendil-works/pi-coding-agent, run pi, connect a provider with the login command, and watch the cost bar during one real task.
• Open a repo that already has an AGENTS.md or CLAUDE.md and check that pi picks it up; compare the agent's first answers with your usual harness on the same prompt.
• Run one conversation, then fork from an earlier node and take a different direction; list ~/.pi/agent/sessions/ to see the JSONL files and their project folders.
• Write a twenty-line our-agent.ts: import createAgentSession, pass a ModelRuntime and an in-memory SessionManager, ask it what the current folder contains, run it with npx tsx.
• Add one defineTool that reads something from your own system (an internal API, a database view, a CSV) and pass it in customTools; confirm the agent calls it unprompted on a relevant question.
• Before any bash-enabled run on a machine you care about, pick one of the three isolation patterns from the containerization guide and set it up.
• Draft a first extension that intercepts bash calls and asks for confirmation on destructive commands; keep it in your project's extensions folder under version control.
• Skim the open issues list once so you know which parts move before you build on them.

Go further

• Read the SDK documentation for the full createAgentSession options list: tool set, system prompt via ResourceLoader, session managers s8.
• Study the three isolation patterns in the containerization guide before shipping anything that runs bash on a user's machine s5.
• Look at pi-chat to see how the same five packages are rearranged for conversation automation instead of coding s6.
• Browse the packages folder and read pi-agent-core on its own: it is the smallest readable version of the loop that every bundled harness runs s2.
• Follow the releases page: v0.84.0 to v0.84.2 shipped within two weeks of August, so expect change notes that affect extensions s4.
• Use the open issues as a map of what is still experimental, starting with the remote session client s7.
• Reuse the skills you already wrote for other tools: pi's skills folder follows the Agent Skills standard s3.

Sources

• pi: the agent toolkit (repository), Earendil Works. Why read it: the README with the package list, the star and fork counts and the MIT license.
• pi monorepo packages, Earendil Works. Why read it: the five packages side by side, the fastest way to see which layer each one owns.
• pi-coding-agent package README, Earendil Works. Why read it: install command, default tools, sessions, and the four extension mechanisms.
• pi releases, Earendil Works. Why read it: the cadence and the changelog for the v0.84 line.
• pi containerization guide (isolation patterns), Earendil Works. Why read it: the three isolation patterns to apply before enabling bash anywhere that matters.
• pi-chat: the same bricks applied to conversation automation, Earendil Works. Why read it: a second product built from the same packages, useful to judge how reusable they are.
• pi open issues, Earendil Works. Why read it: the live list of what is unstable or experimental in the current version.
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. Why read it: the exact option names for createAgentSession, defineTool and the session managers.

FAQ

Can pi replace my daily coding agent today?

Not as a drop-in. It ships without permission prompts, isolation is left to you, and the version line is pre-1.0 with around a hundred open issues. Keep your current harness for work and run pi beside it.

Do I need MCP to give pi a custom tool?

No. defineTool takes a name, a description, a typed parameter schema and an execute function, and the tool is passed to createAgentSession in customTools. It behaves like a built-in tool, with no separate process or protocol.

Will my existing AGENTS.md, CLAUDE.md and skills work?

Yes. The CLI auto-loads the AGENTS.md or CLAUDE.md in your project, and its skills folder follows the Agent Skills standard, so existing skills load unchanged.

Why only four default tools?

read, write, edit and bash are the whole default set, far fewer than the agents on the market, and the project presents that as a choice. Anything else is added deliberately through customTools or an extension.