Design Philosophy

✓ Fresh · 2026-02-24

Pi is intentionally minimal. It avoids dictating features, instead providing a foundation that adapts through extensibility. This page explains what Pi deliberately omits and why.

Core Principle

The core stays minimal; any workflow is possible through extensibility.

Pi's design philosophy is that a coding agent should be a harness, not a framework. It provides the essential infrastructure (LLM communication, tool calling, session management) and leaves everything else to the user.

What Pi Intentionally Omits

No MCP (Model Context Protocol)

Why not: MCP adds protocol complexity and dependencies.

Pi's approach: Build CLI tools with READMEs (skills) or add integrations via extensions. You get the same capability without being locked into a protocol.

Instead of:          Do this:
MCP server     -->   Extension with pi.registerTool()
MCP config     -->   Skill file with instructions
MCP protocol   -->   Direct tool execution

No Built-in Sub-Agents

Why not: Built-in sub-agent patterns impose architectural opinions.

Pi's approach: Multiple options, all user-controlled:

• Spawn separate Pi instances
• Use the subagent-widget.ts extension
• Use the agent-team.ts extension
• Build your own pattern via the extension API

No Permission Popups

Why not: Built-in permission systems are either too strict (blocking legitimate work) or too permissive (providing false security).

Pi's approach: Run Pi in a container for full isolation, or build custom confirmation flows via extensions like damage-control.ts. You define your own security policy.

No Plan Mode

Why not: Plan modes impose a specific workflow (plan first, then execute).

Pi's approach: Write plans to files, use TODO.md, or build a plan-mode extension. The agent naturally plans when instructed to in the system prompt or skill.

No Built-in To-Dos

Why not: To-do tracking is an application concern, not an agent concern.

Pi's approach: Use TODO.md files, tilldone.ts extension, or any project management system. The agent reads and updates whatever tracking system you already use.

No Background Bash

Why not: Background processes reduce observability and can cause subtle issues.

Pi's approach: Use tmux for full terminal observability. What you see is what the agent sees.

The Extensibility Spectrum

Pi sits at the minimal end of the spectrum. The advantage is maximum flexibility; the trade-off is that you configure more yourself.

Benefits of This Approach

1. No Opinion Lock-in

Pi never forces you into a specific workflow. If you want plan-then-execute, write that into your skill. If you want the agent to just dive in, do not add a plan step. Your workflow, your rules.

2. Composition Over Configuration

Instead of a settings panel with hundreds of options, Pi gives you composable building blocks:

Building Block	What It Provides
Extensions	Custom tools, commands, event handlers
Skills	Domain knowledge and procedures
Prompt Templates	Standardized user prompts
Themes	Visual customization
Packages	Distribution and sharing

Stack them in any combination.

3. Transparency

Everything is visible:

• Sessions are plain JSONL files you can inspect
• Extensions are TypeScript files you can read
• Skills are Markdown files you can edit
• Settings are JSON files you can version control
• No hidden state, no black boxes

4. Community-Driven Features

The package system means features come from the community, not from a product roadmap. If someone needs a feature, they build an extension and share it. No waiting for the vendor.

The Pi Way

Traditional Agent	Pi Way
"We added X feature"	"You can build X with an extension"
"Configure X in settings"	"Write an extension that does X"
"X is not supported"	"Build X yourself — here is the API"
"Use our MCP integration"	"Call any API directly from an extension"
"Our agent decides the workflow"	"Your skills and extensions define the workflow"

When This Philosophy Works Best

Pi's minimal approach works best when:

• You have specific workflow requirements
• You want full control over agent behavior
• You value transparency and inspectability
• You are comfortable with TypeScript
• You want to use multiple LLM providers
• You want to share and reuse configurations

It may not be ideal when:

• You want everything to work out of the box
• You prefer GUI configuration
• You do not want to write TypeScript
• You need a single vendor-supported solution