If you've been following the AI coding agent space, you've likely heard of Claude Code, GitHub Copilot, or Codex. But there's a fast-moving open-source alternative sitting at over 46,000 GitHub stars that deserves a serious look: pi, from earendil-works/pi.

This article walks you through what pi actually is, how to get it running in under five minutes, and whether it's worth adding to your workflow.

What Is Pi?

Pi is a monorepo of tools built for constructing and running AI agents. The centerpiece is a coding agent CLI — a terminal-based assistant that can read your files, write code, run shell commands, and iterate on tasks, all within your actual project directory.

The repo is built entirely in TypeScript and ships as a set of npm packages:

• @earendil-works/pi-coding-agent — the interactive CLI you'll use day to day
• @earendil-works/pi-agent-core — the agent runtime (tool calling, state management) for building your own agents
• @earendil-works/pi-ai — a unified LLM API layer that normalizes OpenAI, Anthropic, Google, and others behind one interface
• @earendil-works/pi-tui — a terminal UI library with differential rendering
• @earendil-works/pi-web-ui — web components for AI chat interfaces

Setup in Five Minutes

Prerequisites: Node.js installed, and an API key or existing subscription (Claude Pro, ChatGPT Plus, or GitHub Copilot).

Step 1: Install

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

That's the whole install. No Docker, no Python environment, no build step.

If you prefer another package manager:

pnpm add -g @earendil-works/pi-coding-agent
# or
yarn global add @earendil-works/pi-coding-agent
# or
bun add -g @earendil-works/pi-coding-agent

Step 2: Authenticate

Pi supports two authentication paths.

Option A — Subscription login (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot):

Start pi from any directory and run:

pi
/login

A prompt will appear to select your provider. This stores credentials in ~/.pi/agent/auth.json.

Option B — API key:

export ANTHROPIC_API_KEY=sk-ant-...
pi

You can use OPENAI_API_KEY, GOOGLE_API_KEY, or others the same way. The /login command can also store API keys interactively so you don't need to export them every session.

Step 3: Start a session

Navigate to your project and launch:

cd /path/to/your/project
pi

Pi starts in interactive mode and loads your project directory as its working context. Type a request and press Enter:

Summarize this repository and tell me how to run its checks.

Out of the box, the agent has access to four tools: read (read files), write (create or overwrite files), edit (patch files), and bash (run shell commands). Additional read-only tools like grep, find, and ls are available through tool options.

Key Features Worth Knowing

Context files

Pi loads AGENTS.md (or CLAUDE.md) files at startup to give the model project-specific instructions. You can have a global one in ~/.pi/agent/AGENTS.md and a per-project one in your repo root. Example:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Run /reload inside a session to pick up changes without restarting.

File references

Type @ in the editor to fuzzy-search and reference files, or pass them on the command line:

pi @src/app.ts @src/app.test.ts "Review these together"

You can paste images with Ctrl+V (Alt+V on Windows) or drag them into supported terminals.

Session management

Sessions are saved automatically. Resuming is straightforward:

pi -c         # Continue most recent session
pi -r         # Browse previous sessions

Inside a session, /fork and /clone let you branch the conversation tree — useful when you want to try two different approaches to a problem without losing your current state.

Non-interactive (one-shot) mode

Pi works well in scripts and pipelines:

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

For automation, --mode json gives structured event output and --mode rpc allows stdin/stdout process integration.

Shell commands mid-session

Prefix a command with ! to run it and send the output to the model:

!npm run lint

Use !!command to run it without adding the output to the model's context window.

Model switching

Use /model or Ctrl+L to change models mid-session. Shift+Tab cycles thinking levels. This is useful if you want a fast cheap model for exploration and a smarter one for final implementation.

Using Pi as a Library

If you're building something on top of pi rather than using it as a CLI, the SDK path is clean:

import {
  AuthStorage,
  createAgentSession,
  ModelRegistry,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

await session.prompt("What files are in the current directory?");

For non-Node.js integrations, pi supports RPC mode over stdin/stdout with JSONL framing — so you can integrate from any language.

Building from Source

If you want to contribute or run from source:

git clone https://github.com/earendil-works/pi.git
cd pi
npm install       # Install all dependencies
npm run build     # Build all packages
npm run check     # Lint, format, and type check
./pi-test.sh      # Run pi from sources (any directory)

Note: npm run check requires a prior npm run build because the web-ui package needs compiled .d.ts files from dependencies.

Is It Worth a Try?

Yes, with some caveats.

Pi earns attention for a few concrete reasons:

It's genuinely multi-provider. Most coding agents are tied to one model provider. Pi normalizes across OpenAI, Anthropic, Google, and others at the API layer, so you can switch without re-learning a tool. If you already pay for Claude Pro or GitHub Copilot, pi can use those subscriptions directly — no extra API costs by default.

The session model is well-designed. Branching, forking, and resuming sessions is something most similar tools handle poorly. Pi treats this as a first-class feature, which matters when you're doing long iterative work.

The extensibility story is solid. Extensions are TypeScript modules that can add tools, slash commands, event handlers, and custom UI. If the built-in tools don't cover your workflow, you can add to them.

Where it's less compelling: The terminal UI won't appeal to everyone, and if you're deeply embedded in VS Code with Copilot already working, the switching cost is real. The documentation is good but spread across many individual files in the repo — there's no single polished docs site yet.

For developers who want control over their AI tooling, prefer the terminal, or need to build agents programmatically rather than just use them interactively, pi is a serious option. It's the kind of tool that rewards spending an hour with it.

Quick Reference

Repo: github.com/earendil-works/pi