Open Source Project #187: Pi — Philosophy-Driven Minimal AI Coding Agent, 86k Stars, 30+ LLM Providers, Unlimited Extensibility

Introduction

"Adapt pi to your workflows, not the other way around."

This is article #187 in the "One Open Source Project a Day" series. Today's project is Pi — a philosophy-driven minimal AI coding agent harness with 86,334 Stars, created by Mario Zechner (libGDX author).

Pi has an unusual README section called "Philosophy" that lists what it deliberately doesn't do: no MCP, no sub-agents, no permission popups, no plan mode, no built-in to-dos, no background bash. Each item is followed by the reason and "if you really need it, implement it with an extension."

This isn't missing functionality — it's a design stance: keep the core minimal, handle all customization through the extension layer, don't force users to accept the tool author's preferred workflow.

86k Stars, created August 2025, MIT license.

What You'll Learn

• Pi's 5 npm packages and their responsibilities
• Four run modes: interactive/print/JSON/RPC/SDK
• The Session Tree design
• Extension ecosystem: Extensions, Skills, Prompt Templates, Pi Packages
• Pi's philosophy: what it deliberately doesn't include, and why
• The 30+ LLM provider list and how to switch

Prerequisites

• Basic terminal/command-line experience
• General understanding of AI coding agents (tool-calling, system prompts)
• TypeScript basics help for understanding extension development

Project Background

Overview

Pi is a "harness" for AI coding agents — an accurate word: it's a framework for harnessing LLMs, not a fixed product. It packages LLM integration, agent loops, TUI rendering, and session management as independent npm packages, letting you pick and extend what you need.

Author / Team

• Author: Mario Zechner (badlogic, creator of the libGDX game framework)
• Primary language: TypeScript
• License: MIT
• Website: pi.dev

Project Stats

• ⭐ GitHub Stars: 86,334+
• 🍴 Forks: 10,721+
• 📄 License: MIT
• 📅 Created: 2025-08-09

Five npm Packages

Pi is a monorepo with core functionality split into five independent npm packages:

This split lets you use only pi-ai as a unified LLM API layer, or just pi-agent-core embedded in your own application, without having to take the entire coding agent CLI.

Quick Start

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# or
curl -fsSL https://pi.dev/install.sh | sh

Set an API key or log in with a subscription account:

export ANTHROPIC_API_KEY=sk-ant-...
pi

pi
/login  # choose a provider (supports subscriptions: Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot)

Default tools out of the box: read, bash, edit, write, grep, find, ls. No configuration required — just start chatting.

30+ LLM Providers

Pi's built-in provider list is one of the most comprehensive among coding agent tools:

Subscription accounts (no API key required):

• Anthropic Claude Pro/Max
• OpenAI ChatGPT Plus/Pro (Codex)
• GitHub Copilot

API key access:

• Anthropic, OpenAI, Azure OpenAI, DeepSeek
• Google Gemini, Google Vertex, Amazon Bedrock
• Mistral, Groq, Cerebras, xAI
• Cloudflare AI Gateway, Cloudflare Workers AI
• OpenRouter, Vercel AI Gateway
• Hugging Face, Fireworks, Together AI, Baseten
• NVIDIA NIM, Kimi For Coding, MiniMax
• Xiaomi MiMo (including China, Amsterdam, Singapore endpoints)
• ZAI Coding Plan (Global/China), OpenCode Zen/Go
• Ant Ling

Local inference:

• llama.cpp router server (/login llama.cpp + /llama to manage model downloads)

Switch models with Ctrl+L to open the picker, or via command line:

pi --model openai/gpt-4o "help me refactor this code"
pi --model sonnet:high "solve this complex problem"  # with thinking level

Four Run Modes

Interactive Mode (Default)

TUI-based interactive terminal, top to bottom:

• Header: keyboard shortcuts, loaded AGENTS.md, templates, skills, extensions
• Message area: conversation, tool call results, errors, extension UI
• Editor: border color indicates thinking level
• Bottom status bar: working directory, session name, token usage (↑ input / ↓ output / R cache reads / W cache writes / CH cache hit rate), cost, current model

Print Mode (Non-Interactive)

pi -p "summarize this codebase"
cat README.md | pi -p "summarize this text"   # stdin pipe support

JSON Mode

pi --mode json "help me analyze this problem"
# outputs all events as JSONL, suitable for script processing

RPC Mode

pi --mode rpc
# stdin/stdout JSONL protocol, suitable for non-Node.js process integration

SDK Mode (Embedded Use)

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 
const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});
 
await session.prompt("What files are in the current directory?");

Session System

Session Storage

Sessions are stored as JSONL files in ~/.pi/agent/sessions/, grouped by working directory. Each record has an id and parentId, naturally supporting a branching tree structure without needing multiple files.

pi -c              # continue the most recent session
pi -r              # browse and select session history
pi --no-session    # ephemeral mode, no saving
pi --name "task"   # named session

Session Tree

This is a unique design in Pi: press Escape twice to open the /tree view, navigate the entire session history tree, and jump to any historical node to continue work from there.

/tree shortcuts:
  Search: type a keyword
  Collapse/expand branch: Ctrl+← / Ctrl+→
  Page: ← / →
  Filter mode: Ctrl+O (default → no-tools → user-only → tags-only → all)
  Copy message: Ctrl+X
  Add bookmark: Shift+L

/fork: create a new session file from a historical node (re-send after modifying).
/clone: copy the current branch to a new session file, continue from the current point.

Context Compaction

When long sessions approach the context window limit, Pi supports automatic or manual compaction:

/compact            # manual compact
/compact focus API  # compact with custom instructions

Auto-compaction is on by default, triggering when approaching context limits or on overflow retry. Full history stays in the JSONL file, accessible via /tree.

Extension Ecosystem

Extensions (TypeScript)

Extensions are Pi's most powerful mechanism: TypeScript modules that can add custom tools, commands, shortcuts, event handlers, and UI components.

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

What extensions can do (from the README):

• Custom tools (or completely replace built-in ones)
• Sub-agents and plan mode
• Custom context compaction and summarization
• Permission gating and path protection
• Custom editors and UI components
• Status bar, header, footer, overlay
• Git checkpoints and auto-commit
• SSH and sandboxed execution
• MCP server integration
• Make Pi look like Claude Code
• Games (someone actually implemented Doom to play while waiting)

Extensions go in ~/.pi/agent/extensions/ (global) or .pi/extensions/ (project-level).

Skills

Following the Agent Skills standard, on-demand capability packages in Markdown format:

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when the user asks about X.
 
## Steps
1. Do this
2. Then that

Invoked manually via /skill:name, or auto-selected by the agent based on the SKILL.md description.

Prompt Templates

<!-- ~/.pi/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

Type /review in the editor to auto-expand.

Pi Packages

Bundle extensions, skills, templates, and themes for sharing via npm or git:

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1   # pinned version
pi list
pi update --all
pi config    # enable/disable extensions, skills, templates

⚠️ Security warning: Pi Packages run with full system permissions. Review source code before installing any third-party packages.

Pi's Philosophy: What It Deliberately Doesn't Do

Pi's Philosophy section lists each feature it doesn't include, along with the reasoning:

This "deliberately minimal" philosophy means Pi's core won't bloat with features over time, and it won't force users into a fixed workflow. The trade-off: out-of-the-box experience is not as polished as feature-complete tools; you need time to configure it before it reaches an ideal state.

Supply-Chain Security

Pi's approach to dependency security deserves a dedicated mention:

• Exact version pinning: All direct external dependencies pinned to exact versions (save-exact=true); internal workspace packages use range versions
• Minimum release age: .npmrc sets min-release-age=2, avoiding same-day published dependencies
• package-lock.json as single source of truth: Pre-commit hook blocks accidental lockfile changes (requires PI_ALLOW_LOCKFILE_CHANGE=1 to override)
• Shrinkwrap: Published CLI packages include npm-shrinkwrap.json, locking transitive dependencies for npm users
• CI audit: Regular npm audit --omit=dev + npm audit signatures --omit=dev
• Lifecycle script allowlist: An explicit allowlist; a new dependency with lifecycle scripts fails the check until reviewed

Message Queue (Sending While Agent Works)

A subtle design detail: while an agent is executing tool calls, you can queue messages ahead of time:

• Enter — queue a "steering" message, sent immediately when the current tool call completes
• Alt+Enter — queue a "follow-up" message, sent after the agent finishes all work
• Escape — abort and restore the queued message to the editor

This solves the common scenario of "the agent is going off track, but I don't want to brutally interrupt it."

Resources

Official Links

• 🌟 GitHub: earendil-works/pi
• 🌐 Website: pi.dev
• 📖 Docs: pi.dev/docs/latest
• 📦 npm: @earendil-works/pi-coding-agent
• 💬 Discord: discord.com/invite/3cU7Bz4UPx
• ✍️ Author blog post: mariozechner.at/posts/2025-11-30-pi-coding-agent

Summary

Pi is a tool with a clear design stance: better to have a minimal core that requires user configuration than a feature-packed black box that's hard to modify. 86k Stars shows this stance has found its audience.

Three engineering decisions worth noting:

The Philosophy section: Actively declaring what you won't build — with reasons — is rare in open-source tools. It lets users decide before installing whether the tool fits them, rather than discovering a "standard feature" is missing after the fact.

5 independent npm packages: TUI, LLM API, and agent runtime are each independent, meaning you can use just pi-ai as a multi-provider unified layer, or pi-agent-core to embed an agent loop in your own application. You don't have to accept the entire CLI.

Session branching tree: JSONL + parentId tree structure means branching doesn't require multiple files — all history lives in one file, navigable at any time via /tree. This design is uncommon in other coding agent tools.

Investment in supply-chain security: Exact dependency pinning, lockfile pre-commit protection, regular CI auditing, shrinkwrap for transitive dependencies — this level of attention exceeds most developer tools.

If you have specific ideas about how Claude Code or Codex workflows should work, and you're willing to invest a bit of configuration time rather than taking things out of the box, Pi's extension system gives you enough space to reshape it into exactly what you want.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.