Pi: A Coding Agent That Refuses to Own Your Workflow

The Problem

Coding agent tools are turning into full IDE-shaped products: plan mode, sub-agents, permission popups, task lists, MCP, memory systems. Everything is included. That is not always what you want.

Some teams do not need a black-box agent that takes over the workflow. They need an agent harness that can fit into their existing process. Tools should be replaceable. Models should be swappable. UI should be adjustable. Permissions should be yours to define.

That is where Pi gets interesting. It is not a drop-in “Claude Code alternative” or a terminal clone of Cursor. It is a deliberately small coding agent foundation: usable by default, but designed so you can reshape it into your own workbench. If you want the broader architecture context first, read the existing Agent Harness architecture guide.

Project Overview

Pi is an open-source TypeScript agent harness monorepo from earendil-works, released under the MIT license. On GitHub, it is already a five-figure star project, and the repository was still actively pushed on May 23, 2026.

The monorepo is split into four main packages:

• @earendil-works/pi-coding-agent: interactive terminal coding agent CLI
• @earendil-works/pi-agent-core: agent runtime with tool calling, state management, and event streaming
• @earendil-works/pi-ai: unified multi-provider LLM API
• @earendil-works/pi-tui: terminal UI library with differential rendering

That package split tells you the project is not just a CLI. The coding agent is the product surface. Agent-core and pi-ai are the reusable layers underneath it. You can run Pi as a terminal tool, or embed the runtime inside your own app.

Why This One

Pi has a clear design philosophy: keep the core small, expose the extension points.

The README is unusually direct about what Pi does not include by default: no built-in sub-agents, no plan mode, no built-in to-dos, no permission popups, no MCP. At first glance, that looks like missing functionality. It is actually the point.

Pi is not saying those features are useless. It is saying they should not all be hard-coded into the core. You can add them back with extensions, skills, prompt templates, themes, or third-party Pi packages. That trade-off makes sense for teams that already have their own engineering rules and operational habits.

How It Differs From Claude Code and Cursor

Claude Code and Cursor win on complete default experience. Pi wins on malleability.

If all you want is an AI tool that edits a few files, Pi may not be the easiest choice. You need to understand providers, extensions, settings, and permissions. But if you want any of the following, Pi’s structure starts to feel right:

• Add internal tools without waiting for upstream support
• Embed an agent runtime into a web app, Slack bot, or desktop app
• Switch between providers while preserving context
• Define your own permission, sandboxing, approval, and audit flows
• Package prompts, skills, themes, and extensions for your team

Pi is not the more beginner-friendly tool. It is the more shapeable one.

Quick Start

The official global install is straightforward:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

There is also an install script:

curl -fsSL https://pi.dev/install.sh | sh

With an API key:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Or use an existing subscription after launching Pi:

/login

By default, Pi gives the model four tools: read, write, edit, and bash. That default set is small and easy to reason about. Add more capabilities through skills, extensions, or Pi packages.

The Code That Matters

The CLI is useful, but the more interesting part is that the runtime can be embedded directly.

A minimal agent with @earendil-works/pi-agent-core looks like this:

import { Agent } from "@earendil-works/pi-agent-core";
import { getModel } from "@earendil-works/pi-ai";

const agent = new Agent({
  initialState: {
    systemPrompt: "You are a helpful assistant.",
    model: getModel("anthropic", "claude-sonnet-4-20250514"),
  },
});

agent.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("Hello!");

This is the real value of Pi: the agent loop, message stream, tool execution, and state management are exposed as composable APIs. You can build a terminal app with it, but you can also build an agent into your own product.

Pi-ai is similarly practical. It is not just a wrapper around one SDK. It provides a unified provider and model abstraction across Anthropic, OpenAI, Azure OpenAI, Google, Vertex AI, Mistral, Groq, xAI, OpenRouter, Vercel AI Gateway, GitHub Copilot, Amazon Bedrock, DeepSeek, Kimi, MiniMax, Xiaomi MiMo, and more.

For agent applications, that matters. Model choice is not a static dependency. It changes with cost, latency, quality, rate limits, regional availability, and subscription access. Pi treats model switching as a first-class concern instead of a patch added later.

Community and Ecosystem

GitHub metadata shows Pi as a five-figure star project with thousands of forks. Issues, Discussions, and pull requests are enabled, and the repo was active on May 23, 2026.

Its contribution policy is strict: new issues and PRs from new contributors are auto-closed by default, then reviewed daily by maintainers. That may feel odd if you are contributing for the first time, but it also shows the maintainers are managing noise deliberately.

The supply-chain posture is more impressive. The README says npm dependency changes are treated as reviewed code changes: direct external dependencies are pinned, package-lock is the source of truth, the published CLI includes shrinkwrap, CI uses ignore-scripts, and scheduled workflows run npm audit plus signature checks.

That is not decorative security language. For a coding agent that can execute local commands, install extensions, and run third-party packages, supply-chain hardening is part of the product.

Where It Fits and Where It Does Not

Pi is best for three groups.

First, developers who want a controllable coding agent. If you want to add tools, change prompts, tune the UI, or swap providers, Pi’s extension model fits.

Second, teams building agent products. You can use pi-agent-core and pi-ai as the foundation, then wrap them in your own frontend, permission system, and internal tools.

Third, researchers and builders studying agent workflows. Sessions, branching, compaction, tool events, and provider handoffs are exposed clearly enough to observe how the agent actually behaves.

But do not pick Pi because you want the lowest-friction default experience.

It requires Node 22.19 or newer, and the ecosystem is moving quickly. It intentionally avoids built-in MCP, plan mode, sub-agents, and permission popups. You need to install, write, or trust extensions for those behaviors. Pi packages and extensions also run with full system access, so you should read source before installing third-party packages.

In short: Pi is for people who want control. It is not for people who want the tool to decide the workflow for them.

Verdict

Pi is worth watching not because it is another coding agent CLI, but because it turns a coding agent into a modular, embeddable, extensible TypeScript runtime.

If you are building your own agent workflow, or if existing tools feel too opinionated, Pi deserves a serious look. It will not decide how you should work. It gives you the hooks to build that workflow yourself.

Repository: https://github.com/earendil-works/pi