Why Developers Are Switching to Pi: Minimal Agent Harness with Tree Sessions

What is Pi

Pi is defined by its official site as a minimal agent harness. It organizes models, tools, context, sessions, and terminal interactions so an agent can work in a project, and users adapt the harness to their own workflows. The design philosophy is captured in two slogans: Primitives, not features — prioritize basic building blocks and pre‑install as few features as possible — and Adapt Pi to your workflows, not the other way around — the workflow should dictate Pi's shape.

Installation is straightforward: download from the official site https://pi.dev/ and run pi in the terminal.

Pi vs. Other Coding Agents

Claude Code and Codex come with more pre‑built product capabilities (permission control, plan mode, etc.). Pi keeps only the stable, universal parts in its core and pushes everything else to an extension layer. Neither approach is objectively better; the difference lies in default capabilities and configuration cost.

Minimal Toolset

In its coding‑agent form Pi defaults to just four tools for the model: read, write, edit, and bash. The author initially questioned whether four tools are enough, but benchmarks from Composio and Databricks show Pi matching or exceeding Codex and Claude Code on success rate, cost, and latency across 26 tasks.

Additional built‑in tools — grep, find, ls — are available but not enabled by default. They can be activated with a command like:

pi --tools read,grep,find,ls -p "Review the code"

Flags --exclude-tools and --no-builtin-tools allow fine‑grained control. The author speculates that bash already covers most shell needs, making the three specialized tools redundant by default. This aligns with a discussion in AI Agents in Depth (chapters 2, 4, 5) about keeping tools basic and composable so the model can orchestrate them for search, modification, and verification.

Extension Layer

Four tools handle many tasks, but stable workflows need more. Features common in Claude Code/Codex — fixed prompts, specialized tools, permission control, MCP, sub‑agents, plan mode, built‑in todos, background Bash — are not in Pi's core. Instead they are added via four extension mechanisms:

extension — Change Pi's runtime capabilities. Typical content: tools, commands, events, keybindings, UI, permission flows.

skill — Save a loadable working method or reference. Typical content: capability description and execution steps.

prompt template — Reduce repetitive input. Typical content: Markdown prompts expandable via /name.

package — Distribute and compose resources. Typical content: bundles of extensions, skills, prompts, themes.

The trade‑off: capabilities are added on demand, but users must maintain boundaries themselves. The official docs show extensions can implement custom tools, plan mode, permission control, session compression, sandboxes, and MCP. Before installing a package, inspect its source code and maintenance status to avoid security risks.

Pi vs. DeepSeek Harness (DSH)

DSH's core idea is Everything is a plugin. Both avoid baking all capabilities into the core, but they focus on different problems:

Pi asks how small a coding agent's default core can be. It provides a working minimal harness first, then lets users grow capabilities outward.

DSH asks whether an agent runtime's parts can be disassembled, replaced, and recomposed. Model integration, session storage, loop scheduling, and UI are all plugins; the runtime is treated as an orchestratable system.

Pi suits developers with a clear coding workflow who want to start from a small core. DSH suits those researching agent runtime composition or needing to swap low‑level modules.

Pi's Most Distinctive Features

Tree‑Shaped Sessions

Pi stores sessions as JSONL with id and parentId fields, forming a tree. Commands for navigation: /tree — Jump to a historical node within the same session file and continue; original subsequent records are preserved. /fork — Create a new session file from a user message. /clone — Copy the current active branch into a new session file. /export — Export HTML or JSONL. /share — Upload as a private GitHub Gist and generate a share link.

Auto‑compact is enabled by default; manual /compact is also available. Compression discards some context but the full history remains in the JSONL file. After compression, /tree can still reach the original nodes.

Example workflow: while implementing a feature, the author wants to try a second approach without losing the first. Using /tree, they select an earlier user message ("What are you running?"), choose a branch summary option (No summary / Summarize / Summarize with custom prompt), and continue from that node. Both paths stay in the same session file, switchable via /tree. For permanent separation, use /fork; to duplicate the current state, use /clone. Tree sessions are ideal for agent trial‑and‑error because backtracking never erases exploration history.

Permission Boundaries

Pi's security docs state bluntly:

Pi does not include a built‑in sandbox. Built‑in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process.

Pi runs with the launching user's permissions and has no runtime permission prompts. It does have a Project Trust mechanism that asks once per directory whether to trust project settings, resources, packages, and extensions — but it does not intercept subsequent tool calls. The four default tools already enable reading/writing local files, executing commands, and accessing external services; extensions can further alter tool and runtime behavior.

Users need risk awareness. Key scenarios and mitigations:

Installing unfamiliar package — Risk: extension can execute arbitrary code. Handling: check source, origin, and maintenance before install.

Entering unfamiliar repository — Risk: project resources may alter agent capabilities. Handling: inspect resources before entering the project.

Running high‑risk commands — Risk: launching user may have excessive privileges. Handling: use low‑privilege account, container, or Gondolin isolation.

Only need code search — Risk: unnecessary exposure of write/execute capabilities. Handling: run pi --tools read,grep,find,ls.

The official repo provides a Gondolin extension as an isolation example. Stronger boundaries can be achieved by running Pi in a controlled container, VM, or low‑privilege account — though containers alone are not a complete guarantee. Permission configuration is only one layer of cost; what rules and tools load at startup also affects maintenance burden.

Context Loading

Pi does not dump the entire project directory into the model at startup. Instead it prepares fixed resources first, then adds session history, user messages, and tool results as the task progresses. The context categories:

System Prompt — Loaded content: default system prompt, .pi/SYSTEM.md, ~/.pi/agent/SYSTEM.md, APPEND_SYSTEM.md. Role: SYSTEM.md replaces default; APPEND_SYSTEM.md appends.

Project Rules — Loaded content: ~/.pi/agent/AGENTS.md, parent and current directory AGENTS.md or CLAUDE.md, AGENTS.override.md. Role: load project conventions; AGENTS.override.md replaces same‑directory AGENTS.md / CLAUDE.md.

Tools & Extensions — Loaded content: default read, write, edit, bash plus tools from extensions/packages. Role: tell model which capabilities are callable.

Session State — Loaded content: session JSONL, current active branch, compact‑generated summaries. Role: resume existing session, continue current task.

Current Interaction — Loaded content: user messages, assistant replies, tool results. Role: drive the current round of work.

Project rule files are not limited to the current directory: Pi reads the global ~/.pi/agent/AGENTS.md, then walks up parent directories, finally processing the current directory's AGENTS.md or CLAUDE.md. An AGENTS.override.md in a directory replaces that directory's context file while other directories continue merging. This mirrors Claude Code's behavior but Pi natively supports more file types.

System prompt files offer another entry point: project‑level .pi/SYSTEM.md and global ~/.pi/agent/SYSTEM.md replace the default system prompt; APPEND_SYSTEM.md appends. To test with only defaults, use --no-context-files or -nc. Claude Code also supports --system-prompt (replace) and --append-system-prompt (append) but requires passing them each launch; Pi persists replacements via SYSTEM.md files.

Pi's initial context is smaller because its default system prompt is tiny, its default tool surface is narrow, and it doesn't pre‑load MCP, sub‑agents, permission confirmation, plan mode, etc. Those are added on demand via extensions/skills/packages. Claude Code loads more at startup: default system prompt, environment info, built‑in tool descriptions, permission rules, CLAUDE.md, CLAUDE.local.md, auto memory, and any configured .claude/rules or MCP servers. This is a startup composition difference, not a guarantee that Pi always uses less context in long sessions.

Practical Example

The author installed needed packages from Pi's official packages page (MCP adapter, web search, etc.), noting that package extensions run with local process permissions so source, maintenance, and code should be vetted — no need to install everything for "completeness." Installed extensions included pi-goal for continuous runs.

Using DeepSeek V4 Flash, the author built a Pomodoro timer. First, Matt Pocock's grill-me skill clarified requirements, producing a goal prompt handed to Pi for execution. Cache hit rates were high, often 100%. The first goal produced acceptable functionality but subpar frontend; the author then applied the taste skill to polish the UI. Total time ~20 minutes. The workflow felt similar to Claude Code/Codex; the real difference is configuration responsibility — Pi users must select and maintain extensions themselves.

This highlights a prerequisite: users should understand harness fundamentals and already have an AI coding workflow. Otherwise, facing a tiny default core makes it hard to judge what to add and which third‑party packages to trust.

Who Is Pi For?

If you want zero‑config, no maintenance of tools/permissions, Claude Code or Codex are less hassle. If you have a stable workflow and want to grow from a minimal agent, Pi fits better; existing MCP servers can be integrated via extensions/packages.

Despite Pi's strong benchmark scores, high cache hits, and cost savings, the author advises against making Pi the first AI coding tool for beginners. Start with a fuller‑featured product on real projects, learn which tools you use and which operations need approval, then configure Pi — your judgment will be sharper and the experience better. You need AI coding experience to list truly needed capabilities, and harness understanding to decide whether they belong in extensions, skills, or the external environment. That experience also helps assess permission scope and maintenance cost when installing shared packages.

Summary

If Claude Code or Codex already cover your workflow stably, switching purely for the sake of change isn't worth it — Pi demands real configuration and maintenance time.

Many prefer Pi because four default tools keep the starting point tiny, while extensions allow per‑project tool and rule adjustments.

However, that freedom brings permission auditing, package maintenance, and rollback challenges; missing any can turn "customizable" into new trouble.

Pi is also a good learning vehicle for agent harness internals. It separates model integration, tool loop, TUI, and session backend into relatively clear packages, with the extension system built into the coding‑agent package. Studying how these parts collaborate is possible directly from the repo source and official docs. The author also recommends reading AI Agents in Depth (chapters 2, 4, 5), which shares design thinking with Pi.

References

Official site: https://pi.dev/

AI Agents in Depth: https://bojieli.github.io/ai-agent-book/book/chapter4/