Pi: A Coding Agent Harness You Can Reshape Around Your Workflow

AI coding tools are increasingly becoming full products: built-in plan mode, permission prompts, sub-agents, MCP, task lists, background jobs, and graphical interfaces.

earendil-works/pi takes a different path: keep the core small, and make the rest open to user extension.

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

Documentation: https://pi.dev/

One-line positioning

Pi is a customizable terminal AI coding agent harness: it provides a coding agent, tool-calling runtime, unified model API, TUI components, and package system so you can adapt the agent to your workflow instead of adapting yourself to the tool.

If many coding agents feel like ready-made products, Pi feels more like a set of building blocks for your own agent setup.

Basic information

Note: stars, forks, versions, and language percentages change over time. Check the GitHub repository for live numbers.

What problem does it solve?

Many agent tools are getting more powerful, but that also creates a problem: the default workflow keeps getting heavier.

Some users want built-in plan mode, permission confirmation, MCP, sub-agents, and a graphical interface. Others want a lightweight, scriptable agent that fits naturally into their terminal workflow.

Pi’s bet is:

Do not put every feature into the core.
Keep the agent harness small.
Expose extension points so users can compose their own workflow.

That is the most interesting part of the project. Pi is not just another replacement for Claude Code or Codex. It is asking a different question: what should the agent foundation look like if individuals and teams want to keep reshaping it over time?

Core features

1. A terminal-first coding agent

Pi’s main entry point is a terminal TUI. It supports the usual AI coding agent workflow: reading project context, calling tools, editing files, running commands, and iterating within a session.

The official positioning is clear: Pi is a minimal terminal coding harness. The goal is not to turn every feature into a fixed button, but to let the tool fit into your terminal habits.

2. Multiple models and providers

Pi uses @earendil-works/pi-ai as a unified multi-provider LLM API.

The website lists providers such as Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, OpenRouter, and Ollama. What you can actually use depends on your configuration, account, and API keys.

This is useful for teams: you can separate the agent workflow from the model vendor instead of replacing the whole tool whenever you switch models.

3. An extensible agent runtime

@earendil-works/pi-agent-core provides agent runtime capabilities such as tool calling and state management.

That means Pi is not only a CLI. It can also be reused as a lower-level agent component. You can embed it in a Node.js application, or call it from another system through RPC or JSON event streams.

4. Skills, prompt templates, extensions, and packages

Pi’s extension model is close to productized context engineering:

• Skills: on-demand capability instructions and tool constraints;
• Prompt templates: reusable prompts;
• Extensions: TypeScript modules that can extend tools, commands, keybindings, events, and the TUI;
• Pi packages: bundled extensions, skills, prompts, and themes that can be shared.

The value is that you do not need to control the agent with one long prompt every time. Stable rules, tools, and workflows can become reusable assets.

5. Session trees and shareable history

Pi stores sessions as trees. You can return to an earlier point, branch from there, export the session as HTML, or share it.

That matters when debugging agent behavior. Real workflows often involve attempts, failures, corrections, and rollbacks. A tree-shaped history is better than a purely linear chat for preserving those decision paths.

An important tradeoff: not everything is built in

Pi’s website has a dedicated “What we didn’t build” section: no built-in MCP, no built-in sub-agents, no built-in permission popups, no built-in plan mode, no built-in todos, and no built-in background bash.

This is not simply a missing feature list. It is a product philosophy:

The core provides primitives. More complex features can be built through extensions, skills, scripts, tmux, or packages.

That tradeoff filters the audience.

If you want a complete, conservative, ready-made agent product, Pi may feel too open-ended. If you want control over the system prompt, context, commands, UI, and runtime behavior, Pi becomes more interesting.

Who is it for?

Good fit

• Developers who spend a lot of time in the terminal;
• People who want to study how AI coding agents are built;
• Teams that want to connect an agent to their own tools, scripts, or products;
• Teams that want to accumulate reusable skills, prompt templates, and extensions;
• Users who need multi-model and multi-provider switching without binding themselves to one platform.

Poor fit

• Users who want a zero-config graphical product;
• Users who do not want to understand terminals, config files, or extension mechanisms;
• Teams that need enterprise-grade permission review, centralized control, audit logs, and SLA out of the box;
• Users who only want the agent to write code immediately and do not care about workflow malleability.

Quick start

The official documentation shows this npm install path:

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

On macOS and Linux, you can also use the installer:

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

Then run it inside a project directory:

pi

Authentication can be done with /login, or by setting provider API keys such as ANTHROPIC_API_KEY. Follow the official docs for the current provider setup details.

How I would try it

If you are only evaluating Pi, do not start by studying every extension mechanism.

A better path:

1. Pick a non-critical repository;
2. Run pi and ask it to read the project and make a small change;
3. Try pi -p "..." in print mode and see whether it fits scripting use cases;
4. Check whether session trees, skills, and prompt templates can capture your repeatable workflows;
5. Only then decide whether to study extensions and packages.

The key question is not whether its first output is impressive. The question is whether you can put your own rules into it and reuse them over time.

Pros and limitations

Pros

• Small core, good fit for terminal-heavy developers;
• Clear extension points for context engineering and custom workflows;
• Broad multi-provider support, reducing model lock-in;
• Session trees, export, and sharing are useful for reviewing agent behavior;
• MIT license, friendly to secondary development and commercial experiments.

Possible limitations

• More freedom also means more learning cost;
• Many advanced capabilities need to be assembled through extensions or external tools;
• It is not as friendly to non-terminal users;
• Team-level permissions, security, and auditing need additional work;
• The maturity of the ecosystem depends on future packages, extensions, and community contributions.

Monetization directions

1. Custom team agent harnesses: build standardized coding-agent workflows for engineering teams on top of Pi.
2. Vertical skills and packages: create installable packages for frontend, data analysis, DevOps, security review, and other workflows.
3. Private enterprise agent foundation: connect model routing, audit logs, permissions, and internal tools into the Pi runtime.
4. Agent workflow consulting: help teams turn prompts, AGENTS.md, skills, templates, and CI verification into durable workflow assets.

Conclusion

Pi’s value is not just that it can write code. Its value is that it breaks a coding agent into layers that can be reshaped: CLI, runtime, model API, TUI, skills, extensions, and packages.

If you want a mature all-in-one product, tools like Codex, Claude Code, or Cursor may be more direct.

But if you care about this question: can my agent grow around my workflow? Pi is worth studying.

It points to an interesting direction: an agent is not only a tool. It can also be an evolving developer workbench foundation.