# Pi: features, protocols, quickstart

## TL;DR

Pi is an MIT-licensed, minimal terminal coding agent and toolkit from earendil-works, with a unified LLM API, an agent runtime and a TUI library alongside the CLI. It is a single agent loop extended through TypeScript extensions, skills and packages; subagents exist only as an example extension. It suits developers who want to shape their own harness.

## Key facts

| Field | Value |
| --- | --- |
| Type | Harness |
| Languages / SDKs | TypeScript |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Other |
| GitHub stars | 110,627 (as of 2026-09-30) |
| GitHub forks | 14,064 |
| Last push | 2026-09-30 |
| Latest release | v0.99.1 |
| Repository | [earendil-works/pi](https://github.com/earendil-works/pi) |
| Website | [pi.dev](https://pi.dev) |
| Documentation | [pi.dev](https://pi.dev/docs/latest) |
| Last verified | 2026-09-30 |

## Key features

- An agent loop with tree-structured JSONL sessions: continue from an earlier entry to branch, fork or clone into a new file, and compact old messages into a summary entry. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/how-pi-works.md))
- Four ways to run the same agent: interactive TUI, print mode, JSON event stream and RPC over stdin and stdout, plus an in-process TypeScript SDK. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/index.md))
- TypeScript extensions loaded into the Pi process register tools, commands, shortcuts, providers, event handlers and UI, and are distributed with skills, prompt templates and themes as Pi packages through npm or git. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/how-pi-works.md))
- MCP client over stdio and streamable HTTP with `pi mcp add`, user and project `mcp.json` files, OAuth, and configurable tool exposure. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md))
- A `codemode` tool that runs JavaScript calling the other tools, for example several in parallel with `Promise.allSettled`, returning only the script's output to the model. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md))
- An example subagent extension that runs each subagent as a separate `pi` process with an isolated context, parallel streaming, and scout, planner, reviewer and worker sample agents. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/subagent/README.md))
- Project trust: project settings, MCP servers, extensions, skills and prompts from a working folder load only after the user grants trust. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md))
- Monorepo packages beyond the CLI: a multi-provider LLM API (pi-ai), an agent runtime (pi-agent-core), a terminal UI library (pi-tui), and durable-runtime and telemetry packages. ([source](https://github.com/earendil-works/pi/blob/main/README.md))

## Architecture and orchestration pattern

Pattern: Other.

Pi is a TypeScript monorepo. The coding agent CLI sits on an agent runtime with tool calling and state management, a unified multi-provider LLM API, and a terminal UI library. All interfaces (interactive, print, JSON, RPC, SDK) use the same agent and session mechanisms.

The design is one agent loop per process. A message is added to the active branch, a model request is built from the system prompt, branch, tools and skill descriptions, tool calls run, and another turn starts if results or queued messages need it. Steering messages enter after the current assistant turn and follow-ups after pending work. The docs describe no built-in delegation; the subagent extension in the examples directory starts each subagent as a separate `pi` process, and multi-agent workflows are prompt templates that chain scout, planner and worker agents.

State is the session file: JSONL entries with parent references form a tree, and compaction inserts summaries while the original entries remain. Memory beyond sessions is left to extensions, skills and context files.

### Human in the loop

Users can steer a running agent with queued messages, abort a run, and branch or fork sessions. Pi has no built-in permission system: tools run with the permissions of the process and it does not ask approval before every tool call, according to the README and security page. Approval and protection behaviour comes from extensions, and the examples include permission-gate, confirm-destructive, protected-paths and plan-mode extensions, or from running Pi in a container or sandbox. Project trust only controls which project resources load.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md) | Client side: connects to MCP servers over stdio or streamable HTTP and exposes their tools and resources to the model; the legacy SSE transport is rejected. No MCP server mode is documented. |
| A2A | Unknown (checked 2026-09-30) | — | No A2A / Agent2Agent mention in the README or docs read; repo code search for a2a returned nothing. |
| AG-UI | Unknown (checked 2026-09-30) | — | No AG-UI mention in the README or docs read; repo code search for ag-ui returned nothing; not checked against a listing in the AG-UI README. |

## Best for

- Developers who want a small terminal agent they can reshape with extensions, skills and prompt templates instead of adopting a fixed workflow. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Embedding an agent loop in a TypeScript application through the SDK, or driving it from another process over JSON or RPC. ([shortlist](https://multiagentguide.top/best/typescript.md))
- Building a custom multi-agent setup on top of a single-loop harness, starting from the example subagent extension.
- Running an agent inside a container, micro-VM or policy sandbox, which the docs describe as the main way to add boundaries. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))

## Not for

- Users who want built-in subagents, teams or parallel sessions; the docs describe a single agent loop, and delegation exists only as an example extension.
- Users who need permission prompts out of the box; there is no built-in permission system.
- Contributors who expect open issues and PRs from anyone; new contributors' issues and PRs are auto-closed by default.

## Quickstart

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

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i @earendil-works/pi-coding-agent --ignore-scripts` (no -g) ok, `npx --no-install pi --version` ok, @earendil-works/pi-coding-agent 0.99.1. The official command uses `-g`; the same package was installed locally with `--ignore-scripts`. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```bash
# Node.js 22.19 or newer
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# or, on macOS or Linux
curl -fsSL https://pi.dev/install.sh | sh

cd /path/to/project
pi
# inside Pi: /login to connect a subscription or API key, then type a task

# Add an MCP server, check it, start Pi
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi
```

### Common pitfalls

- Requires Node.js 22.19 or newer; the documented npm install uses `--ignore-scripts` because Pi needs no dependency lifecycle scripts.
- Pi has no built-in permission system and runs with your account's permissions; containerize or sandbox it for untrusted repositories or unattended use.
- Project trust does not sandbox tool calls; it only gates loading of project settings, extensions, skills, prompts and MCP config.
- MCP servers must use stdio or streamable HTTP; SSE entries are rejected.
- Inside tmux, enable extended keys so Shift+Enter and Enter are distinguishable.
- The repository was previously badlogic/pi-mono; old links and posts may use that name, so use the @earendil-works packages shown in the README.

Official quickstart: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#getting-started

## Pros

- One session tree in JSONL supports branching, forking and compaction without losing the original entries. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/how-pi-works.md))
- The security page states plainly that Pi has no approval gate and that project trust is not a sandbox, and the docs describe three isolation patterns. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md))
- The README documents supply-chain practices: exact-pinned dependencies, a release-age setting, a shrinkwrap for the CLI and audit checks in CI. ([source](https://github.com/earendil-works/pi/blob/main/README.md))
- The same agent can be used interactively, in print and JSON modes, over RPC, or embedded through the SDK. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/index.md))
- MIT licensed with frequent tagged releases and per-package changelogs. ([source](https://github.com/earendil-works/pi/releases))

## Cons

- No built-in permission system: by default Pi runs with the permissions of the launching user and process. ([source](https://github.com/earendil-works/pi/blob/main/README.md))
- Subagents are not built in; the only documented delegation is an example extension that must be symlinked into place and starts separate pi processes. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/subagent/README.md))
- The legacy SSE MCP transport is not supported; only stdio and streamable HTTP work. ([source](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md))
- New issues and PRs from new contributors are auto-closed by default and reviewed by maintainers daily. ([source](https://github.com/earendil-works/pi/blob/main/README.md))
- An open issue reports MCP tools with colliding codemode names invoking the wrong tool. ([source](https://github.com/earendil-works/pi/issues/10239))

## Alternatives

- [Oh My Pi (omp)](https://multiagentguide.top/tools/oh-my-pi.md)
- [OpenCode](https://multiagentguide.top/tools/opencode.md)
- [Claude Code](https://multiagentguide.top/tools/claude-code.md)
- [Codex CLI](https://multiagentguide.top/tools/codex.md)
- [Aider](https://multiagentguide.top/tools/aider.md)

## FAQ

### Does Pi support MCP?

Yes, as a client. Pi connects to MCP servers over stdio or streamable HTTP, configured with pi mcp add or an mcp.json file, and rejects the legacy SSE transport. No MCP server mode is documented.

### Does Pi have subagents?

Not built in. The docs describe a single agent loop per process. The repository includes an example subagent extension that runs each subagent as a separate pi process, which you can install and adapt.

### How is Pi different from Oh My Pi?

Oh My Pi is a separate fork of Pi by another team. Its README says it adds a built-in task tool for subagents, LSP and debugger tools and other features. Pi keeps a minimal core extended through packages.

### Is Pi free and open source?

The repository is MIT licensed and no paid plan is documented. You pay your model provider for usage. The docs describe /login for subscriptions or API keys.

### Was it renamed?

The repository was previously badlogic/pi-mono, and GitHub redirects the old path to earendil-works/pi. The README still refers to pi-mono in its session-sharing section.

## Sources

- [How Pi works](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/how-pi-works.md)
- [Pi docs index](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/index.md)
- [Pi MCP servers doc](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md)
- [Pi CLI reference (codemode)](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md)
- [Subagent example extension](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/subagent/README.md)
- [Run Pi safely (security doc)](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md)
- [Pi README](https://github.com/earendil-works/pi/blob/main/README.md)
- [Pi releases](https://github.com/earendil-works/pi/releases)
- [Issue 10239: colliding codemode MCP tool names](https://github.com/earendil-works/pi/issues/10239)
- [Pi coding agent README, getting started](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#getting-started)
- [Pi website](https://pi.dev)
- [Pi documentation](https://pi.dev/docs/latest)
- [earendil-works/pi GitHub repository](https://github.com/earendil-works/pi)

## Unknown fields

protocols.a2a and protocols.agui: no mentions in the README or docs read; code search for a2a and ag-ui returned nothing; not checked against a listing in the AG-UI README. harnesses: Pi does not launch, drive or install into Claude Code, Codex, OpenCode, OpenClaw or Hermes, so the list is empty. The pi.dev site has no llms.txt (404).

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/pi