pi Deep Dive: The Minimal Architecture Behind 95,000 GitHub Stars

Last updated: August 23, 2026

Official Sources#

All repository numbers in this article were pulled live from the GitHub API on August 23, 2026.

Every coding agent harness now ships the same checklist: sub-agents, plan mode, to-do tracking, permission popups, background shells, MCP support. Claude Code has all of it. So do Codex, opencode, and most of the field. That checklist won the market - and it also produced a class of tools that Mario Zechner, pi's creator, describes as "a spaceship with 80% of functionality I have no use for," whose system prompt and tools change on every release and whose internals inject context behind your back (source).

pi (stylized lowercase, formerly the badlogic/pi-mono repository, now earendil-works/pi) is the counter-argument. It is an MIT-licensed TypeScript toolkit that ships a unified LLM API, an agent loop, a terminal UI library, and a coding agent CLI - and deliberately refuses to ship almost everything else on the checklist. As of August 23, 2026 it holds roughly 95,900 stars and 11,900 forks about twelve months after its repository was created, making it one of the fastest-growing developer tools on GitHub. This is part one of our three-post series on pi: what it is, how its architecture actually works, and why its refusal-to-build philosophy is winning hearts among agent power users.

The Problem: Harnesses Became Products#

Zechner's November 2025 writeup is the clearest statement of the problem pi attacks, and it is worth reading as a requirements document written in anger. His complaints about existing harnesses reduce to three:

1. Context opacity. "Exactly controlling what goes into the model's context yields better outputs... Existing harnesses make this extremely hard or impossible by injecting stuff behind your back that isn't even surfaced in the UI" (origin post).
2. Uninspectable internals. He wanted "a cleanly documented session format I can post-process automatically, and a simple way to build alternative UIs on top of the agent core," and found existing APIs "smell like organic evolution."
3. Prompt churn. Claude Code's system prompt and tools change on every release, which he argues breaks workflows and silently changes model behavior.

His conclusion was to build his own harness with a simple governing rule: "if I don't need it, it won't be built." The name, he admits, was chosen to be "entirely un-Google-able." The joke aged badly - pi is now one of the most-discussed repos in its category - but the design discipline stuck.

The Design: A Composition Kit, Not a Product#

The core design move is visible in the first line of the coding agent README: "Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals."

Concretely, the default surface is tiny. Out of the box the model gets exactly four tools - read, write, edit, and bash - with optional read-only companions (grep, find, ls) you can enable for restricted runs. In the original release, Zechner measured the entire system prompt plus tool definitions at under 1,000 tokens, versus tens of thousands for competitors (origin post). The bet is that frontier models are now RL-trained hard enough on the coding-agent shape that they need almost no instruction. One Hacker News commenter on the launch thread backed this up from the other direction: "It's a great harness for use with smaller parameter size models given the system prompt is quite a bit shorter vs Claude or Codex" (HN).

The second design move is that everything above that floor is user-composable TypeScript. Extensions can register custom tools, commands, event handlers, and UI components; skills follow the open Agent Skills standard; prompt templates are markdown files; and all four asset types can be bundled into shareable "pi packages" distributed via npm or git (customization docs). The README's list of what extensions have already been built includes sub-agents, plan mode, permission gates, MCP integration, git checkpointing, SSH execution, and - yes - Doom while you wait.

The Five Packages#

pi is a monorepo whose packages are independently consumable npm modules (repo README):

A separate repository, earendil-works/pi-chat, covers Slack and chat automation.

Three architectural choices inside these packages deserve attention because they explain much of pi's appeal to builders.

Provider abstraction by API shape, not by vendor. pi-ai speaks four underlying wire protocols - OpenAI Completions, OpenAI Responses, Anthropic Messages, and Google Generative AI - and maps providers onto them, rather than writing a bespoke client per vendor (origin post). On top of that sit three subscription auth routes (Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro via Codex, GitHub Copilot), roughly thirty API-key providers, and a llama.cpp router for local models (providers docs). The distinctive feature is mid-session model switching with best-effort context handoff: switch from Anthropic to OpenAI and your thinking traces are converted into <thinking>-tagged text blocks so the conversation continues coherently (origin post). Aborts are supported through the entire pipeline, including tool calls, with partial results returned rather than discarded.

A TUI that respects the terminal. pi-tui deliberately does not take over the screen like a full-screen app. It writes to the normal scrollback buffer and only redraws changed lines using differential rendering, wrapped in synchronized-output escape sequences to prevent flicker (origin post). You keep your terminal emulator's native scrolling, search, and selection - the things full-screen TUIs famously break. The tradeoff, and the source of the most persistent user complaints we cover later, is that very large sessions do more line comparison work than an alt-buffer design would.

Supply-chain paranoia. The repo treats dependency changes as reviewed code changes: direct external dependencies pinned to exact versions, a two-day minimum release age during resolution (min-release-age=2), a shrinkwrap shipped inside the published CLI package, installs run with --ignore-scripts, and an explicit allowlist for dependency lifecycle scripts (repo README). For a tool that executes arbitrary code by design, that hardening is not decorative.

Session Trees: JSONL Files That Branch#

The most quietly influential piece of pi is its session format, documented precisely enough that people build external tooling on it (session-format docs).

Sessions live at ~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl, organized by working directory. Each line is a JSON object. The first line is a session header; every entry after it carries an 8-character id and a parentId, forming a tree inside a single file rather than a linear transcript. Entry types include messages, model_change (mid-session provider switches are recorded as entries), thinking_level_change, compaction, branch_summary, labels (bookmarks), and custom entry types that extensions can persist without polluting LLM context.

That tree structure is what powers the commands users cite when they explain why they switched:

• /tree opens a navigable view of the whole session; select any previous point and continue from there, switching between branches with all history preserved in one file.
• /fork creates a new session file from any previous user message on the active branch, placing the selected prompt back in the editor for modification.
• /clone duplicates the current active branch into a new session at the current position.

Rebuilding context is a deterministic walk: buildContextEntries() walks from the current leaf to the root, honors any compaction entries on the path, and buildSessionContext() converts the result into the message list sent to the model (session-format docs). Nothing about your history is hidden state. You can parse the file yourself with twenty lines of code, export sessions to HTML, or publish real work sessions as datasets the way Zechner does on Hugging Face (badlogicgames/pi-mono dataset).

Compaction Without Amnesia#

Compaction is where the session tree earns its keep. Auto-compaction triggers when contextTokens > contextWindow - reserveTokens (16,384 tokens reserved by default). Pi walks backwards from the newest message until it accumulates 20,000 tokens (keepRecentTokens) - those stay verbatim - then hands everything older to the LLM with a structured summary template covering goal, constraints, progress, key decisions, next steps, and critical context, plus running lists of read and modified files (compaction docs).

The mechanics have real care in them: cut points never split a tool call from its result; a single oversized turn produces a "split turn" with merged prefix summaries; repeated compactions re-summarize from the previous kept boundary so nothing survives twice or zero times; tool results are truncated to 2,000 characters during serialization to keep summarization requests affordable. And because compaction is lossy but the JSONL is not, the docs remind you that "the full history remains in the JSONL file; use /tree to revisit" (coding agent README). Extensions can intercept both compaction (session_before_compact) and branch summarization (session_before_tree) to cancel, replace, or reroute summarization entirely - the hook that one Hacker News commenter used to answer a complaint about selective summarization with "You can do that in Pi!" (HN compaction thread).

When you jump branches via /tree, pi offers to generate a branch_summary of the abandoned path and injects it into the new branch, so exploration does not evaporate (compaction docs).

Four Run Modes: One Agent, Many Frontends#

The same agent core runs in four modes (coding agent README):

1. Interactive TUI. The default, including a message queue with distinct semantics: Enter queues a steering message delivered after the current assistant turn finishes its tool calls; Alt+Enter queues a follow-up delivered only when all work completes.
2. Print / JSON. -p prints a response and exits (reading piped stdin into the initial prompt); --mode json streams every event as JSON lines.
3. RPC. --mode rpc exposes the agent over stdin/stdout using strict LF-delimited JSONL framing - explicitly documented so non-Node clients can drive pi, and warned about in detail ("Do not use generic line readers like Node readline, which also split on Unicode separators") (RPC docs). This is how third parties wrap pi: an Emacs package drives pi over RPC, and one extension author reports testing extensions against "a dummy LLM that emits canned responses" the same way (HN launch thread).
4. SDK. Import createAgentSession from the published package and embed the whole harness in your own app (SDK docs).

This is the architecture decision that turns users into ecosystem builders. Because every mode shares the same session format and event stream, a headless fleet, a phone client, a CI job, and your terminal all see the same agent. Real examples surfaced within months: a macOS-native sandboxed client built on top of headless pi (Show HN, August 2026), and a developer who imported pi's own tool implementations into an MCP bridge in an afternoon, writing that "Pi happens to be modular enough that the surgery is trivial" (Ask HN, May 2026).

The Philosophy: What pi Refuses to Build#

The Philosophy section of the coding agent README is the closest thing the project has to a manifesto, and it is quoted here verbatim because the specific refusals are the product:

Pi is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with extensions, skills, or installed from third-party pi packages. This keeps the core minimal while letting you shape pi to fit how you work.

No MCP. Build CLI tools with READMEs, or build an extension that adds MCP support.

No sub-agents. There's many ways to do this. Spawn pi instances via tmux, or build your own with extensions, or install a package that does it your way.

No permission popups. Run in a container, or build your own confirmation flow with extensions inline with your environment and security requirements.

No plan mode. Write plans to files, or build it with extensions, or install a package.

No built-in to-dos. They confuse models. Use a TODO.md file, or build your own with extensions.

No background bash. Use tmux. Full observability, direct interaction.

Two of these deserve unpacking because they are the most controversial.

No MCP is a position, not an omission. Zechner's argument (full post) is that popular MCP servers dump their entire tool catalogs into context on every session - he cites Playwright MCP at 21 tools and 13.7k tokens - while a CLI tool with a README costs nothing until the agent reads the README on demand. We covered the general pattern separately in CLIs Over MCPs; pi operationalizes it.

No sub-agents comes with an actual theory attached. Zechner's case: sub-agents are "a black box within a black box" with poor context transfer, and mid-session sub-agents are usually a symptom of failing to gather context up front. Spawn pi inside tmux instead and you get full observability and the ability to interact with the child agent directly (origin post). Notably, the community data cuts both ways. One long-time user reported that going subagentless made tasks complete faster: "When the main model gives an isolated task to the subagent, the latter goes wild producing a comprehensive report... Without the handoff, the main model does the job much more precisely and conservatively" (HN minimalism thread). Another countered that subagents are how he routes cheap models at grunt work. Both camps can be served - pi just refuses to pick for you.

The same logic governs safety. Pi ships no permission system at all and says so plainly: "Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it" (repo README). The official answer is containerization, documented in three patterns: a Gondolin extension routing tools into a local Linux micro-VM, plain Docker, or the OpenShell policy-controlled sandbox (containerization docs). A project-level trust system gates whether project-local settings and extensions load at all (settings docs), but inside a trusted project the agent runs unconstrained.

Traction: From Protest Project to 95K Stars#

The origin story matters here because it explains the trust. Mario Zechner (GitHub: badlogic, currently the repo's top contributor with over 3,500 contributions) had been through open-source commercialization before: he created libGDX, the most-used Android game framework of the early 2010s, and lived through RoboVM being sold to Xamarin and promptly closed-sourced, after which the community fork carried the tech forward (acquisition post). pi began as his personal protest harness in the badlogic/pi-mono repository, created August 9, 2025, with the founding blog post landing November 30, 2025.

Attention arrived via a side door. Peter Steinberger built OpenClaw on top of pi, and when Armin Ronacher wrote publicly about that relationship in January 2026, the interest migrated downstream: Zechner reports spending the following two months taking "3-5 calls per day" from VCs and large companies (acquisition post). On April 8, 2026 he announced he was joining Earendil - the company founded around Ronacher - and bringing pi with him. The repository moved from badlogic/pi-mono to earendil-works/pi. The terms read like a checklist drawn from the RoboVM trauma: pi stays MIT "forever, non-negotiable," the trademark (not license tricks) is the protection mechanism, Zechner keeps technical direction, and future commercialization follows a published three-tier plan of MIT core, Fair Source value-adds, and proprietary enterprise infrastructure (acquisition post; licensing RFC).

The growth record, checked against primary sources as of August 23, 2026:

• Roughly 95,900 stars and 11,900 forks in twelve months (GitHub API).
• The February 24, 2026 Hacker News launch hit 608 points with 306 comments (HN); the August 4 minimalism discussion pulled 551 points and 296 comments (HN); the August 13 compaction explainer drew 211 points (HN).
• Third-party trend digests recorded pi on GitHub trending repeatedly in August 2026: +492 stars on August 8, +924 on August 15, +518 on August 16 (startupcorners digests).
• An ecosystem of distributions formed, the way it does around editors: opinionated configurations like LazyPi (151-point Show HN) and oh-my-pi, which one commenter compared to "LazyVim/AstroVim" distributions (HN minimalism thread). Derivative and adjacent projects trend alongside the original.
• The cadence is industrial: 255 tagged releases since December 2, 2025, averaging close to one per day, currently at v0.84.2 (releases feed).

But the more telling signal is who adopts it and how they talk about it. The minimalism thread produced the community's own taxonomy: "Codex, Claude Code are VS Code, Jetbrain. Pi is Neovim" (HN). Another user: "Pi is the shape of the thing that should exist." A third, on why he loves it despite the friction: "I love hacking away at pi extensions... I would not be surprised if tools like Claude Code needing to be all things for all people is hurting their peak usefulness." Even rival-tooling discussions now treat pi as table stakes - when a user asked on August 22 whether the Herdr multiplexer was worth it, the framing was that "Agent Mutliplexing (per tab) is already implemented in claude code, codex, pi (with plugins)" (HN) - and our own coverage of Herdr's rise shows pi users building the same fleet patterns natively.

The cost angle has its own evidence base: a Databricks-run benchmark discussed in August 2026 found pi's lean context discipline among the cheapest per-task harnesses, which we analyzed in The Harness Is the New Cost Lever.

The Honest Limits#

pi's minimalism is a trade, and its users say so more bluntly than its README does.

You own the orchestration burden. No sub-agents, no plan mode, no to-dos means no scaffolding for decomposing big jobs - by design, but still on you. A launch-thread convert put it precisely: "Pi I've tried headless and it's fine but you kinda have to wire up the exit conditions yourself since it's so minimal by design" (HN). The Emacs comparison cuts the same way: "using Pi is exactly like using Emacs. For anything you want to build you can ask your agent and it will build it... At the same time half the code is buggy, UI elements will try to overlap one another, and you'll periodically get crashes" (HN minimalism thread).

Sandboxing is DIY. The absence of auto-approval-with-sandbox is the most-cited functional gap: "The biggest issue with Pi is that they don't have proper sandboxing with auto approval. Most solutions are third party and half baked" (HN minimalism thread). The official patterns require setting up containers or micro-VMs yourself.

The default TUI strains on long sessions. A developer who ultimately built his own native macOS client over headless pi reported that "the default TUI on Mac OS... hogs the CPU as the session gets large, history keeps shifting under your nose making reading or copying from it hard" (Show HN) - the known cost of scrollback-preserving differential rendering.

Governance is intentionally sharp-edged. New contributors' issues and PRs are auto-closed by default pending maintainer review (repo README), a slop-filtering policy that is honest about the agent-generated contribution flood but unusual for a project this size. And the project is still pre-1.0, moving at nearly a release a day - pin your version.

None of these are accidents; each traces directly to a philosophical refusal. Whether they are disqualifying depends entirely on whether you want a product or a kit.

FAQ#

What exactly is pi?#

pi is an MIT-licensed, open-source AI agent toolkit from Earendil, organized as a TypeScript monorepo: a unified multi-provider LLM API (pi-ai), an agent loop runtime (pi-agent-core), a differential-rendering terminal UI library (pi-tui), a telemetry contracts package, and a self-extensible interactive coding agent CLI (pi-coding-agent) that combines them (repository).

How many GitHub stars does pi have?#

Roughly 95,900 stars and 11,900 forks as of August 23, 2026, twelve months after the repository was created on August 9, 2025 (GitHub API). Verify live numbers at the link, as the count moves quickly.

Who created pi?#

Mario Zechner, known as badlogic on GitHub and previously the creator of the libGDX game framework. He built pi as a personal minimal harness, joined Earendil with it on April 8, 2026, and retains technical direction (announcement).

Does pi support MCP servers?#

Not built in - this is explicit policy, not an omission: "No MCP. Build CLI tools with READMEs, or build an extension that adds MCP support" (Philosophy section). The rationale is token cost and composability; MCP support exists as a third-party extension if you want it.

How do pi sessions work under the hood?#

Sessions are JSONL files stored under ~/.pi/agent/sessions/ where every entry carries an id and parentId, forming a tree. /tree navigates and switches branches in place, /fork and /clone extract new sessions, and compaction summarizes old context while the full history remains in the file (session-format docs).

What models and providers can pi use?#

Three subscription routes (Claude Pro/Max, ChatGPT Plus/Pro via Codex, GitHub Copilot), roughly thirty API-key providers including Anthropic, OpenAI, Google, DeepSeek, Groq, Cerebras, xAI, and OpenRouter, plus a llama.cpp router for local models - with mid-session model switching and cross-provider context handoff (providers docs).

Can pi be embedded in other applications?#

Yes, three ways beyond the interactive TUI: print/JSON mode for scripting, RPC mode over stdin/stdout with LF-delimited JSONL framing for non-Node processes, and a TypeScript SDK exposing createAgentSession for embedding the whole harness (RPC docs; SDK docs).

Is pi safe to run unsandboxed?#

No, and the project says so itself: pi has no built-in permission system and runs with your user's full permissions. The official guidance is to containerize it using the documented Gondolin micro-VM, Docker, or OpenShell patterns (containerization docs).

---

This deep dive is part one of a three-part series on pi. Part two is a hands-on guide to run modes and session trees, and part three is a head-to-head comparison with Claude Code and opencode. For the newest rival in the minimal lane, see fx vs pi. The related posts above go deeper on the cost benchmark behind pi's context discipline, the Herdr multiplexer that sits above harnesses like this one, and the CLI-over-MCP philosophy pi takes to its logical extreme.

Continue Reading#

• Best CLI Tools for Developers - more terminal agents and harnesses compared
• Claude Code vs Codex - two of the harnesses mentioned here, head to head
• Oh My Pi (omp): Model Roles, Advisor and Fallbacks - a batteries-included Pi fork with LSP, subagents and role-based model routing
• Agent Skills Moves to the Agentic AI Foundation - the Agent Skills standard now has a vendor-neutral home