pi-mono: The Minimal AI Agent Toolkit with 44k+ GitHub Stars

Tosin Akinosho

— 5 min read

pi-mono is a TypeScript monorepo that provides a complete toolkit for building AI agents. Created by Mario Zechner, it has grown to 44.3k GitHub stars and represents a radically different philosophy: minimal core, maximum extensibility. Unlike bloated agent frameworks, pi-mono gives you only what you need and lets you build everything else yourself—or ask your agent to build it for you.

The project is actively maintained (latest commit 24 minutes ago as of May 2026) and powers production systems including OpenClaw, the viral AI agent that made headlines earlier this year. If you're building AI agents and tired of frameworks that dictate your workflow, pi-mono deserves your attention.

What is pi-mono?

pi-mono is not a single tool—it's a collection of five carefully designed packages that layer on top of each other. The philosophy is radical: do one thing well, make it composable, and let developers build the rest.

The core insight is that LLMs are genuinely good at writing and running code. So instead of building guardrails and restrictions, pi-mono embraces this capability. It provides the minimal scaffolding needed for an agent to read files, write files, edit files, and execute bash commands. Everything else—sub-agents, plan mode, permission gates, MCP integration—can be built as extensions or skills when you actually need them.

Created by Mario Zechner (who previously built game engines and understands software quality deeply), pi-mono is written with exceptional care. It doesn't flicker, doesn't consume excessive memory, and doesn't randomly break. The codebase is clean, the documentation is thorough, and the extension system is genuinely powerful.

Core Features and Architecture

1. pi-ai: Unified Multi-Provider LLM API

The foundation is a unified LLM API that abstracts 15+ providers: Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, and more. Instead of learning each provider's quirks, you write once and switch models mid-session. The API handles provider-specific peculiarities (different token counting, reasoning trace formats, tool calling implementations) transparently.

What makes pi-ai special is context handoff. Switch from Claude to GPT mid-session, and Claude's thinking traces convert to <thinking> tags that GPT understands. Sessions serialize to JSON, making them portable and debuggable. Token and cost tracking work across all providers on a best-effort basis.

2. pi-agent-core: Agent Runtime with State Management

The agent loop handles the full orchestration: process user messages, execute tool calls, feed results back to the LLM, repeat until done. But pi-agent-core adds the useful bits: state management, message queuing (one-at-a-time or all-at-once), attachment handling, and a transport abstraction that lets you run agents directly or through a proxy.

The loop emits events for everything, making it trivial to build reactive UIs or integrate into other systems.

3. pi-tui: Terminal UI Framework with Differential Rendering

Instead of using existing TUI libraries, Zechner built a minimal framework optimized for chat interfaces. It uses "differential rendering"—only redrawing lines that changed—to eliminate flicker. Synchronized output escape sequences ensure atomic updates. The result: smooth, responsive terminal interactions that feel native.

Components are simple: render(width) returns an array of strings with ANSI codes. Containers collect lines from children. The TUI compares to previous state and only redraws what changed. Caching prevents re-rendering unchanged content.

4. pi-coding-agent: The CLI That Ties It Together

The actual coding agent CLI with session management, model switching, project context files (AGENTS.md), slash commands, custom prompt templates, OAuth authentication, and HTML export. But here's what makes it different: the system prompt is 200 tokens. The toolset is four tools: read, write, edit, bash.

That's it. No permission popups, no plan mode, no built-in to-dos, no MCP support, no background bash, no sub-agents. Each omission is intentional and documented. If you need these features, you build them as extensions or ask your agent to build them.

5. pi-web-ui: Web Components for Chat Interfaces

Reusable web components for building chat UIs. Useful if you want to embed pi's agent core into a web application or build alternative interfaces.

Get free AI agent insights weekly

Join our community of builders exploring the latest in AI agents, frameworks, and automation tools.

Join Free

Getting Started

Installation is straightforward. For the CLI:

npm install -g @mariozechner/pi-coding-agent
pi

This launches the interactive terminal UI. Set your API key (Anthropic, OpenAI, or any supported provider) via environment variables or OAuth, and you're ready to start coding with an agent.

For building custom agents, install the packages you need:

npm install @mariozechner/pi-ai @mariozechner/pi-agent-core @mariozechner/pi-tui

The documentation includes examples for building agents from scratch, creating extensions, adding custom tools, and integrating with other systems. The README files are comprehensive and the codebase is readable.

Real-World Use Cases

1. Self-Modifying Agents - Ask pi to build an extension that does X, and it writes the code, reloads itself, and keeps working. This is the core philosophy: software building software.

2. Production AI Systems - OpenClaw uses pi-mono as its foundation. It connects pi to communication channels (Slack, Discord, etc.) and lets agents run code in response to messages. The architecture is clean enough to support this at scale.

3. Context Engineering - The minimal system prompt and extensible architecture let you control exactly what goes into the model's context. Load AGENTS.md files hierarchically (global, per-project, per-directory). Inject custom messages via extensions. Implement RAG or long-term memory. Full control.

4. Multi-Model Workflows - Start with Claude for reasoning, switch to GPT for speed, use a local model for cost savings. Sessions transfer seamlessly between providers.

How It Compares

vs. Claude Code - Claude Code is powerful but opaque. You can't see the system prompt, can't control context injection, and features change with each release. pi-mono is transparent and stable. The tradeoff: Claude Code has more built-in features, but pi-mono lets you build exactly what you need.

vs. Cursor - Cursor is an IDE with AI features. pi-mono is a pure agent framework. Different use cases. Cursor is better for IDE-integrated coding; pi-mono is better for automation and custom workflows.

vs. LangChain - LangChain is a general-purpose LLM framework with 122k+ stars. pi-mono is specifically for coding agents. LangChain is more flexible but heavier; pi-mono is lighter and more opinionated.

The key difference: pi-mono's philosophy is "minimal core, maximum extensibility." You get the essentials and build the rest. Other frameworks try to include everything, which adds complexity and bloat.

What's Next

The roadmap includes message compaction (auto-summarizing older messages when approaching context limits), tool result streaming (display bash output as it arrives), and improved session branching. But the core is stable. Zechner has stated that pi-mono won't add MCP support, built-in to-dos, plan mode, or background bash—not because they're hard, but because they're not needed and add unnecessary complexity.

The real future of pi-mono is in the ecosystem. As more developers build extensions and skills, the framework becomes more powerful without the core becoming bloated. This is the vision: a minimal, stable foundation that the community extends.

Sources

Read more