1. Origins & Philosophy
Pi.dev (by Mario Zechner)
Pi started as a personal project by Mario Zechner (creator of libGDX) out of frustration with existing unified LLM APIs — particularly the Vercel AI SDK’s poor handling of tool calling with self-hosted models. The core thesis is radical minimalism: a coding agent needs only 4 tools (read, write, edit, bash) and a system prompt under 1,000 tokens. Everything else is opt-in via extensions.
Pi’s tagline could be summed up as: “Frontier models have been RL-trained up the wazoo — they inherently understand what a coding agent is.” Trust the model, keep the harness small.
Claude Agent SDK (by Anthropic)
The Claude Agent SDK was born from Claude Code’s internal infrastructure at Anthropic. Originally called the “Claude Code SDK,” it was renamed in late 2025 when Anthropic realized the same agent loop powering their coding tool could power research agents, email assistants, finance analyzers, and more. It ships everything Claude Code uses: a rich tool suite, hooks system, subagents, MCP integration, and context management (compaction).
Its philosophy: “Give agents a computer.” Real shell access, real file system operations, with production-grade safety boundaries.
2. Architecture Overview
Pi.dev — Layered Monorepo
Pi is structured as a TypeScript monorepo (pi-mono) with clearly separated layers:
| Package | Role |
|---|---|
@mariozechner/pi-ai | Unified multi-provider LLM API — streaming, tool calling, token/cost tracking, cross-provider context handoffs |
@mariozechner/pi-agent-core | Agent runtime — agent loop, state management, message queuing, event subscriptions, transport abstraction |
@mariozechner/pi-coding-agent | The CLI agent — session management, tools, themes, extensions, skills |
@mariozechner/pi-tui | Terminal UI library with differential rendering |
@mariozechner/pi-web-ui | Web components for AI chat interfaces |
@mariozechner/pi-mom | Slack bot delegating to the pi coding agent |
@mariozechner/pi-pods | CLI for managing vLLM deployments on GPU pods |
Key architectural properties:
- Sessions are stored as trees — you can branch, navigate, fork, and rollback like git
- The agent loop runs until the agent says it’s done (no max-steps knob)
- All interactions flow through a unified event-based architecture (
AgentEventtypes) - Cross-provider handoffs are first-class: switching models mid-session preserves context, thinking blocks get auto-converted
- Full abort support throughout the entire pipeline including tool calls
- 4 operating modes: Interactive, Print/JSON, RPC (stdin/stdout JSONL), SDK (embeddable)
Claude Agent SDK — Agent Runtime as Library
The Claude Agent SDK is available in two implementations:
| Package | Version (March 2026) |
|---|---|
@anthropic-ai/claude-agent-sdk (TypeScript) | v0.2.71 |
claude-agent-sdk (Python) | v0.1.54 |
Core architecture:
- Built around an agentic loop: Gather Context → Take Action → Verify Work → Repeat
- The agent interacts with a sandboxed shell — real file system, real commands
- Two API surfaces:
query()(fire-and-forget async iterator) andClaudeSDKClient(bidirectional, interactive sessions with hooks/tools) - Context management via automatic compaction — summarizing conversation when the context window fills
- Built-in tool catalog: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, Agent (subagents), NotebookEdit
- 18 hook events for lifecycle interception (PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, ConfigChange, TeammateIdle, TaskCompleted, WorktreeCreate, etc.)
- Native subagent support — agents can delegate to specialized agents running in isolated context windows
- Worktree isolation: subagents can run in temporary git worktrees for blast-radius control
3. Provider Support & Model Lock-in
Pi.dev — Provider Agnostic
Pi supports 15+ providers natively:
Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, OpenRouter, Ollama, vLLM, LM Studio, and any OpenAI-compatible endpoint.
- Switch models mid-session with
/modelor Ctrl+L - Cycle favorites with Ctrl+P
- 5 unified thinking levels (off/minimal/low/medium/high) across all thinking-capable models
- Custom providers via
~/.pi/agent/models.json - Built-in cost tracking per session — makes provider routing data-driven
- Only includes models that support tool calling (essential for agentic workflows)
Claude Agent SDK — Claude Only
- Locked to Anthropic’s Claude models (Opus, Sonnet, Haiku families)
- Supports Anthropic API, AWS Bedrock, Google Vertex AI, and Azure as providers
- No support for OpenAI, Google Gemini, or open-source models
- Enables Claude-specific features impossible on agnostic frameworks: extended thinking mode, computer use, Claude-optimized prompting
- API key authentication required (no claude.ai login for third-party agents)
4. Tool System
Pi.dev
Built-in tools (4 by default): read, write, edit, bash
That’s it. The bash tool provides access to everything else (git, npm, docker, curl, etc.). Additional tools like find, grep, ls are available via --tools flag but not loaded by default.
Tool definitions use TypeBox schemas for type-safe validation via AJV. Schemas are serializable as plain JSON — good for distributed systems.
const weatherTool: Tool = {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: Type.Object({
location: Type.String({ description: 'City name' }),
units: StringEnum(['celsius', 'fahrenheit'])
})
};
No MCP by design. Pi deliberately excludes MCP, arguing that CLI tools with READMEs (Skills) or extensions that add MCP support are more flexible. This is a contentious but intentional decision.
Claude Agent SDK
Built-in tools (10+): Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, Agent (subagents), NotebookEdit, MultiEdit
- Tools follow the naming convention
mcp__<server-name>__<tool-name>for MCP-sourced tools - Deep MCP integration — connect servers via stdio or HTTP, tools auto-discovered
- SDK MCP servers: define tools as Python functions with
@tooldecorator, run in-process (no separate process needed) allowed_toolsis a permission allowlist;disallowed_toolsblocks specific tools- Automatic tool search that lazily loads on-demand to save context window space
5. Session Management
Pi.dev — Tree-Structured Sessions
Sessions are trees, not linear histories:
/treenavigates the session tree in-place — select any previous point, branch off- All branches live in a single file
/forkcreates a new session from any branch point- Sessions auto-save to
~/.pi/agent/sessions/organized by working directory - Export to HTML with
/export, share via GitHub gist with/share - Filter modes: default → no-tools → user-only → labeled-only → all
- Custom messages in session files for extensions to store state (not sent to LLM)
Claude Agent SDK — Linear with Compaction
- Sessions are linear conversations
- Automatic compaction when context window fills — summarizes conversation to free space
PreCompacthook lets you archive full transcript before summarization- Session resumption via
session_id— pass the ID to continue where you left off - No built-in persistence layer — sessions don’t survive server restarts unless you build that yourself
- Multi-session architecture for long-running tasks: initializer agent + coding agent pattern
6. Extensibility Model
Pi.dev — Multi-Layer Extension System
| Mechanism | Description |
|---|---|
| Extensions | TypeScript modules with 20+ event hooks — in-process async handlers that can block, modify, transform, access session state, render UI |
| Skills | CLI tools with SKILL.md READMEs — the agent reads the README to learn how to use the tool |
| Prompt Templates | Reusable prompt patterns |
| Themes | Visual customization (colors, layout) |
| Pi Packages | Share everything above via npm or git — activate with one line of config |
The operations abstraction means every tool’s underlying implementation is swappable.
Claude Agent SDK — Hooks + MCP + Subagents
| Mechanism | Description |
|---|---|
| Hooks (18 event types) | Callbacks that intercept agent behavior at lifecycle points — can block, modify, inject messages, log |
| MCP Servers | Connect external tools/services via Model Context Protocol |
| SDK MCP Servers | In-process Python/TS tools via @tool decorator |
| Subagents | Delegate tasks to specialized agents with own tools, prompts, context windows |
| Plugins | Directories containing hooks, commands, agents, skills — with an emerging marketplace |
| Settings Files | .claude/settings.json, project-level config, CLAUDE.md files |
7. Safety & Permissions
Pi.dev — YOLO by Default
- No permissions by default — runs everything without asking
- No sandbox, no pre-screening
- Philosophy: “Security in coding agents is mostly theater; if it can write and run code, it’s game over”
- Permission-gate extension available but opt-in
- Recommendation: run in a container for isolation
Claude Agent SDK — Safe by Default
- Deny-first permissions with 5 modes:
default,plan,acceptEdits,bypassPermissions,dontAsk - Filesystem sandbox with configurable boundaries
- Haiku pre-screening of bash commands before execution
- Extensive guardrails (~10K tokens of behavioral rules, formatting instructions, safety constraints)
- Worktree isolation for risky operations
- Plugin subagents cannot define hooks, MCP servers, or permission modes — must be elevated to
.claude/agents/for those capabilities
8. Subagent / Multi-Agent Patterns
Pi.dev
- No built-in sub-agents — by design
- Achievable via: spawning pi instances in tmux, SDK orchestration scripts, RPC mode, or extension-based approaches
- Community extensions exist for sequential pipelines (agent-chain) and parallel dispatch
- The pi-pi meta-agent demonstrates delegating to specialized framework experts
Claude Agent SDK
- First-class subagent support via the
Agenttool - Each subagent gets its own context window, tools, prompt, and instructions
- Subagent lifecycle hooks:
SubagentStart,SubagentStop - Worktree isolation: subagents can work in temporary git worktrees
- Background subagents with progress summaries
TeammateIdleandTaskCompletedhooks for coordination- Agent definitions via YAML/JSON files in
.claude/agents/
9. Common Workflows
Both SDKs support:
| Workflow | Pi Approach | Claude Agent SDK Approach |
|---|---|---|
| Code review | Use read + bash tools, switch to cheaper model for lint | Subagents for security/style/tests in parallel |
| Bug fixing | Interactive session, branch to try different approaches | Agentic loop: read → diagnose → fix → test → verify |
| Refactoring | Tree-branching: try multiple strategies, rollback | Worktree isolation for risky changes |
| Long-running tasks | Continue sessions, fork for side-quests | Initializer + coding agent across context windows |
| CI/CD integration | pi -p (print mode) for non-interactive pipelines | query() with structured output |
| Embedding in apps | createAgentSession() SDK API | query() or ClaudeSDKClient |
| Multi-channel bots | pi-mom (Slack), OpenClaw (Discord/Telegram/WhatsApp) | Custom integration via SDK + hooks |
10. Key Differentiators
Pi.dev Unique Strengths
- True model agnosticism — route tasks to the best/cheapest model per use case
- Tree-structured sessions — non-linear history with branch/fork/rollback
- Built-in cost tracking — per-session token and cost metrics across providers
- Radical minimalism — sub-1000-token system prompt, maximum context for actual work
- Full transparency — every token visible, no hidden orchestration
- MIT license — fully open source
- Self-hosting support — pi-pods for managing vLLM deployments on GPU pods
- Message queuing — inject guidance while the agent executes tools
Claude Agent SDK Unique Strengths
- Production-tested at scale — the exact infrastructure powering Claude Code used by hundreds of thousands of developers
- 18 hook events — deepest lifecycle interception of any framework
- Native subagents — first-class multi-agent delegation with isolated contexts
- Automatic compaction — context management that enables arbitrarily long sessions
- Deep MCP integration — connect Slack, GitHub, Playwright, and hundreds of servers
- Safety by default — deny-first permissions, sandboxing, command pre-screening
- Worktree isolation — git-based blast-radius control for parallel work
- Dual language SDKs — Python and TypeScript with near feature parity
11. Decision Matrix
| Criterion | Pi.dev | Claude Agent SDK |
|---|---|---|
| Model lock-in | None (15+ providers) | Claude only |
| Language | TypeScript only | TypeScript + Python |
| License | MIT | Proprietary (Anthropic Commercial ToS) |
| Default tools | 4 | 10+ |
| MCP support | No (by design, extensible) | Native, first-class |
| Sub-agents | Via extensions/tmux | Built-in |
| Session model | Tree (non-linear) | Linear with compaction |
| Safety defaults | YOLO (opt-in safety) | Deny-first (5 permission modes) |
| Cost tracking | Built-in | Not built-in |
| Self-hosted models | Native (Ollama, vLLM, LM Studio) | Not supported |
| Enterprise readiness | Community-driven | Anthropic-backed |
| System prompt size | ~200 tokens | ~10K tokens |
| Community proof | OpenClaw (145K+ GitHub stars) | Claude Code (millions of users) |
12. When to Choose What
Choose Pi.dev if:
- You need provider flexibility and want to avoid vendor lock-in
- Cost optimization across models is important
- You’re building multi-channel applications (OpenClaw-style)
- You prefer maximum transparency and control
- You work exclusively in TypeScript
- You want to self-host models on your own GPU infrastructure
- You believe in the minimal-harness philosophy
Choose Claude Agent SDK if:
- You’re committed to the Claude ecosystem and want the deepest integration
- Enterprise safety and permission controls are non-negotiable
- You need built-in multi-agent orchestration (subagents)
- MCP server connectivity is a core requirement
- You want Python support
- You need production-proven infrastructure with Anthropic backing
- Long-running agent tasks across multiple context windows are your use case
Sources: pi-mono GitHub (badlogic/pi-mono), pi.dev, npm packages, Anthropic engineering blog, Claude Agent SDK documentation (platform.claude.com), Agentlas comparison, various framework analyses — March/April 2026.
