What Is Pi Coding Agent? Pi.dev Architecture, Extensions and Why Harnesses Build on It

Aug 30, 2026 - Last update: Aug 30, 2026

Problem

I kept seeing the same thing happen in coding-agent discussions: someone already understands DeepSeek Harness, has tried Claude Code, and searches for “DeepSeek Harness vs Pi” — then asks the most basic question of all:

What is Pi?

So let me answer that question first, because everything else only makes sense after it.

Pi is not a model. It is not primarily a polished all-in-one coding product either. Pi is a minimal, vendor-neutral coding-agent harness and runtime: it provides the agent loop, the tool surface, the session model, the provider abstraction, and the extension system around an LLM. You can use it directly through the CLI, or embed the same runtime into your own tools through its SDK and RPC interfaces.

The official package is @earendil-works/pi-coding-agent and the project site is pi.dev. In short: Pi is best understood as programmable agent infrastructure, not as “just another Claude Code alternative.”

Pi agent vs Pi harness: are they the same thing?

Pi is the runtime between models and applications.

If you search for “Pi agent”, “Pi coding agent”, “Pi harness”, or “pi.dev”, you usually land on the same project. The names just emphasize different layers:

Pi harness = the underlying runtime: agent loop, session handling, tools, extensions, provider abstraction
Pi coding agent CLI = the interactive terminal UI built on top of that harness
Pi SDK / RPC = the interfaces to embed the same runtime into another tool or application

So calling Pi “an agent” is not wrong. But seeing it only as a CLI app misses the more interesting part: it is reusable agent infrastructure.

Model Providers (Anthropic / OpenAI / DeepSeek / Local)
        |
        v
+-----------------------------------+
|           Pi harness              |
|  Agent loop                       |
|  Tools                            |
|  Context / Sessions               |
|  Extensions                       |
|  Provider abstraction             |
+-----------------------------------+
        |
        v
CLI / RPC / SDK / Custom Apps

This diagram carries three take-aways at once: Pi is not a model, Pi is not only a CLI, and Pi is a runtime/harness layer in between.

Core philosophy: start tiny, extend everything else

Core philosophy

The default tool surface is intentionally small: read, write, edit, and bash. The read-only tools grep, find, and ls are also built in, and on Windows bash is replaced by powershell. Either way, the point stands: Pi ships a tiny, auditable core and a deliberately short system prompt.

This minimalism is intentional. Pi does not bake a lot of workflow opinion into the core. Capabilities that a commercial agent ships by default — planning, sub-agents, extra tools, permissions, MCP integrations, lifecycle hooks, context transforms, custom commands, UI elements — are added through extensions and packages instead.

The one-sentence summary is: Pi treats many “product features” as composable primitives.

Pi architecture explained

This is the technical core of the article. Four pieces define Pi as a harness: the agent loop, the tool layer, the provider layer, and the session model.

Agent loop

At the center there is still a classic coding-agent loop:

collect context
send a prompt to the model
the model chooses tools
execute the tool
return the result to the model
continue until the task is done

A stable, simple loop is valuable because it is predictable and auditable. When something behaves strangely, you can trace exactly what the model saw and which tools ran.

Pi harness layers: context manager, tool/permission system, loop/scheduler, provider/model adapter, and UI

The picture above shows the layers of a coding-agent harness in general. Pi implements this same stack, but keeps each layer small and replaceable.

Tool layer

The default surface stays tiny so the behavior stays understandable: fewer tools means easier auditing of what the agent can do. When you need more capability, you add it through an extension instead of letting the core grow.

Provider layer

Pi is vendor-neutral. Anthropic, OpenAI, DeepSeek, Google, local models served by Ollama or llama.cpp, and any OpenAI-compatible API are all supported. The official docs describe 15+ providers and hundreds of models, and if you need something custom, an extension can register a provider at runtime with pi.registerProvider.

The key design point is that the model and the harness are decoupled. You can switch models during a session, and you are never locked into one vendor.

Session model

A Pi session is not a simple chat log. The session is stored as a tree of entries, and the SDK gives you structured access: getTree, getPath, labels, branching (sm.branch, sm.branchWithSummary, createBranchedSession), and forking (ctx.fork("entry-id")). There are /new, /resume, and /clone flows, and long sessions produce compaction events (compaction_start / compaction_end) to keep context under control.

Why does this matter for a coding agent? Because you can experiment without losing history, recover from a bad path by branching back to an earlier entry, compact a context window that grows too big, and compare alternative approaches side by side.

Three-slot context window: small fixed system prompt, per-task working memory with plan and current diff, and large on-demand retrieval from files, prior sessions, and external docs

Pi rebuilds the small system prompt and the working-memory parts on every turn, and pulls in the large retrieval slot only when needed. That is how a long-lived coding session stays focused.

Extensions are the real Pi story

The core value of Pi is not the default feature count — it is the extension surface.

Extensions are plain TypeScript modules. They can:

register tools with pi.registerTool (parameters validated through TypeBox schemas)
register slash commands with pi.registerCommand
subscribe to lifecycle events with pi.on("session_start"), pi.on("tool_call"), and more
interact with the UI, session, context, and provider behavior

This is not a plugin directory layered on a closed product. The extension model is how developers shape the harness itself.

Here is a minimal extension that registers a tool, a command, and a lifecycle hook:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }], details: {} };
    },
  });

  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => ctx.ui.notify(`Hello ${args || "world"}!`, "info"),
  });
}

You can share these extensions as packages, and install them from npm or git with the pi install command:

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi install https://github.com/user/repo
pi list

The typical workflow is short: identify a missing capability → write or install an extension → load it → continue working. Tools and commands registered by extensions become available in the running session, and some registrations apply immediately without a restart.

From the community side, developers often describe Pi as attractive because it offers control, predictability, and fewer opaque behaviors. I will come back to that in a dedicated section below.

Why do developers build other agents and frameworks on top of Pi?

Why Frameworks Build on Pi

This is the part that explains the title of this post. Several properties make Pi a good foundation for other tools:

Small stable core. An upper framework does not have to compete with a huge product layer.
Typed extension surface. You extend the runtime in code, not with fragile prompt hacks.
Model neutrality. Frameworks built on Pi are not locked to Claude or GPT.
Embeddability. Pi is not only a CLI. It has interactive mode, print mode, RPC mode, and an SDK, so other apps can use it as an engine.
Reusability. Upper tools focus on orchestration, specialized workflows, UI, collaboration, and domain tools — without reimplementing the loop, tool calling, or session handling.

The core conclusion: Pi lowers the cost of building a custom coding-agent product because developers can reuse the harness layer.

For scripting and embedding, the CLI modes are straightforward:

# Install the harness globally
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Start an interactive session
pi

# Print (non-interactive) mode for scripting and summaries
pi -p "Summarize this codebase"

# RPC mode: JSON protocol over stdin/stdout, for embedding in apps/IDEs
pi --mode rpc

If you want to embed the runtime in your own application, the SDK exposes the session runtime directly:

import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
  const services = await createAgentSessionServices({ cwd });
  return {
    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
    services,
    diagnostics: services.diagnostics,
  };
};

const runtime = await createAgentSessionRuntime(createRuntime, {
  cwd: process.cwd(),
  agentDir: getAgentDir(),
  sessionManager: SessionManager.create(process.cwd()),
});

Pi vs Claude Code: product vs primitives

Claude Code is a polished coding-agent product. Pi is a minimal, programmable agent harness. Both are useful — they just optimize for different users.

Dimension	Pi	Claude Code
Philosophy	Primitives, compose your own	Integrated product
Default features	Minimal	Rich
Model strategy	Vendor-neutral	Claude-centric
Extension model	Deeply programmable	Product-integrated hooks/features
UX	Terminal-first, DIY-friendly	Polished out of the box
Best for	Builders and custom workflows	Developers wanting a finished experience

Claude Code ships more opinionated features by default, such as planning, orchestration, sub-agent workflows, and integrations. Pi leans toward “install or build only what you need.”

Neither is a wrong choice. Pi and Claude Code optimize for different users.

Pi vs DeepSeek Harness: similar philosophy, different decomposition

If you came here from a “Pi vs DeepSeek Harness” search, read our detailed DeepSeek Harness vs Pi comparison for the full picture. This section only covers the architectural relationship, so I will not repeat that article.

Both projects share the same philosophy: a small core, strong extensibility, and behavior that developers can inspect and change — not a pure black-box product.

They decompose the runtime differently:

Pi keeps the agent loop as a central runtime concept, uses a TypeScript extension host, has a mature coding-agent surface, and is broadly vendor-neutral.
DeepSeek Harness is Cordis-based, pushes “everything is a plugin” further, has strong first-party DeepSeek positioning, and relies more on plugin composition and hot reload.

One line: Pi and DeepSeek Harness move in the same direction — away from monolithic coding-agent products — but they decompose the runtime differently.

Why Pi appeals to developers who dislike “black magic”

From the community side, developers often say they chose Pi not because it has more features, but because:

behavior feels predictable
harness changes are under their control
extension code is inspectable
there is less hidden orchestration
there are fewer unexpected product-level changes

For example, one developer (Jilles) said that after using Claude Code, Codex, and OpenCode, Pi became his daily driver because he values direct control over the harness. Another (Christian May) made the point that minimal harnesses appeal to developers who prefer stability, predictability, and extensibility over opaque automation. Some developers describe this as avoiding “black magic”: fewer opaque layers between the model and the workflow.

These are community views, not official claims. Treat them as signals about why people switch, not as technical facts about Pi.

The trade-offs: what Pi does not give you for free

Minimalism is not free. If you pick Pi, you accept:

more responsibility and more configuration
a less polished out-of-the-box experience
feature discovery that may depend on community packages
custom extensions that require TypeScript familiarity
debugging your own extension stack as your job
fewer guardrails, which calls for stronger engineering discipline

The honest way to put it: Pi does not eliminate complexity. It relocates it. Minimalism transfers complexity from the product vendor to the user.

If you want “install → login → start coding”, Claude Code or Codex may fit you better.

Who should use Pi?

User type	Is Pi a good fit?	Why
Multi-model developer	Yes	Vendor-neutral
Harness/framework builder	Strong fit	SDK, RPC, extensions
Developer who wants full control	Strong fit	Small inspectable core
TypeScript-heavy developer	Good fit	Extension ecosystem
Claude-only user wanting polished UX	Maybe not	Claude Code may be simpler
Beginner wanting everything built in	Probably not first choice	More assembly required
Developer building a custom agent product	Strong fit	Reusable runtime
Team avoiding vendor lock-in	Worth evaluating	Provider abstraction

Choose Pi if you want a vendor-neutral agent runtime, want to embed the agent in your own product, prefer composing features yourself, care about predictability, want a small auditable tool surface, or regularly switch models and providers.

Consider something else first if you want the most polished out-of-the-box UX, do not want to maintain extensions, depend heavily on vendor-specific workflows, or prefer built-in planning and sub-agent features over assembling them yourself.

A concrete example: building a custom coding agent on Pi

Imagine you need an internal Java debugging agent. It must read files, run Maven tests, inspect logs, parse stack traces, use company-specific commands, and expose everything through your own web UI.

With Pi you can:

keep the default read / edit / bash tools
add custom Maven and debugging tools through extensions
define lifecycle and context hooks
pick the model provider you already pay for
embed the runtime via SDK or RPC
build the custom UI outside Pi

Internal Web UI
      |
      v
Custom Agent Service
      |
      v
Pi SDK / RPC
      |
      v
Pi Runtime
  |- Model provider
  |- Built-in tools
  |- Custom Java tools
  `- Session / context

Notice that no existing coding-agent product is required here. The product layer — UI, orchestration, domain tools — is yours to build, and the harness layer is already there.

Frequently asked questions

Is Pi a model? No. It is a coding-agent harness and runtime.

Is Pi the same as pi.dev? The site pi.dev is the official home of the Pi coding agent project. When people say “pi.dev”, they usually mean the project itself.

Is Pi agent the same as Pi harness? Mostly yes. “Harness” refers more precisely to the runtime layer, while “Pi agent” is the everyday name for the same project.

Does Pi only work with one model? No. The architecture is vendor-neutral — Anthropic, OpenAI, DeepSeek, Google, and local or compatible providers.

Is Pi a Claude Code replacement? It overlaps in use case, but the two represent different product philosophies: primitives vs integrated product.

Is Pi better than DeepSeek Harness? There is no universal answer. I covered the details in our detailed DeepSeek Harness vs Pi comparison.

Can I build my own agent on Pi? Yes — that is one of its most interesting use cases.

Final verdict

Pi is most interesting when viewed as a programmable coding-agent runtime. Claude Code and Codex emphasize a finished product experience. DeepSeek Harness pushes plugin-oriented architecture deep into the runtime. Pi sits in a distinctive middle layer: small enough to understand, powerful enough to extend, and reusable enough to embed.

If you remember only one thing, remember this: Pi is not primarily trying to give you the most features out of the box. It is trying to give you a small agent harness that you can make your own.

Summary

In this post, I explained what Pi coding agent actually is and why it keeps showing up in coding-agent comparisons. The key point is that Pi is programmable agent infrastructure — a minimal, vendor-neutral harness with an agent loop, a small auditable tool surface, a session tree, a model-neutral provider layer, and a TypeScript extension system — rather than just another coding-agent product.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 pi.dev - Official Site
👨‍💻 Pi GitHub Repository (earendil-works/pi)
👨‍💻 npm Package: @earendil-works/pi-coding-agent
👨‍💻 Pi Docs: Quickstart
👨‍💻 Pi Docs: Extensions
👨‍💻 Pi Docs: SDK
👨‍💻 DeepSeek Harness vs Pi (docs.bswen.com)
👨‍💻 DeepSeek Harness vs Pi: A Beginner's Comparison of Agent Harnesses

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!