Forget Claude Code, Try Pi Agent Instead…

☆ Overview

David Ondrej delivers a comprehensive, step-by-step course on Pi Agent — the minimal, customizable AI coding agent at pi.dev. He covers everything from installation and configuration through context engineering, skills, extensions, prompt templates, the CMAX multi-agent workflow, and the powerful Pi + Codex CLI combo. This is a practical, hands-on walkthrough aimed at both beginners and experienced users who want to unlock Pi's full potential as a personal orchestrator agent.

1 What Is Pi Agent — Product vs. Harness

▶ 0:00

David opens by declaring Pi Agent his daily driver — he uses it even more than Claude Code and Codex. Pi is one of the fastest-growing repositories on GitHub, and he believes it will become the most popular AI agent in the world.

Product vs. Harness

The critical distinction David draws:

• Products (Claude Code, Codex) — mass-market, highly opinionated, bloated, slow, tons of features and guardrails built for tens of millions of users
• Harness (Pi Agent) — minimal, comes with just four tools, a tiny ~1,000 token system prompt, and the rest is up to you

The Pi homepage philosophy: "You should adapt Pi to your workflows, not the other way around."

Why Pi Over Other Agents

• Most minimal agent — easy to customize and change
• ~1,000 token system prompt — 10–15x smaller than other agents (those tokens cost money every message)
• 15+ providers, thousands of models — unlike Codex (OpenAI-only) or Claude Code (Anthropic-only)

2 Installation & Initial Setup

▶ 0:50

Installation is a one-liner from pi.dev — copy the curl command and paste it into any terminal. First-time install takes ~20 seconds.

Authentication & Provider Setup

• Launch Pi by typing pi in the terminal
• Type /login to select a provider — supports subscription-based (ChatGPT) or API key (OpenRouter, etc.)
• David uses OpenRouter — go to openrouter.ai, add credits ($5–10 is enough), create an API key with a spending limit

Model & Thinking Configuration

• /model — select any model available on OpenRouter
• Shift+Tab — cycle thinking effort: off → minimal → low → medium → high → extra high
• David runs on Opus 4.8 Fast at extra high thinking — "Opus 4.8 fast inside of Pi Agent is just incredible"

3 Context Engineering — Three Markdown Files

▶ 5:32

Pi gets context from three main markdown files:

1. SYSTEM.md — overrides the full system prompt entirely. David advises not to touch this unless you know exactly what you're doing
2. APPEND_SYSTEM.md — appends to the end of the system prompt without replacing defaults. This is the safe way to customize Pi's behavior globally
3. AGENTS.md — project-specific context, placed in any working folder. Always loaded when Pi runs in that directory

Claude Code compatibility: Pi also reads existing CLAUDE.md files, so if you have a Claude Code project setup, Pi works there immediately.

David's APPEND_SYSTEM.md Examples

• "Always make your responses clear and concise"
• Date format preference (day/month/year)
• Location context (Poland, Katowice)
• "No emojis. Short, direct English."
• "David can't see tool/bash output. Always relay results in text." — solves the Claude Code problem of agents showing "here are the results" without actual results
• Language auto-detection: respond in the user's language

A key workflow: have Pi update its own context files. Just tell it "find the global Pi folder and update the append system file" with your new instructions.

4 The Four Built-in Tools

▶ 6:36

Pi ships with just four default tools:

• read — read any file
• write — create files
• edit — edit/modify existing files
• bash — the most powerful tool, giving Pi full terminal control

Everything else (web search, etc.) is added through extensions. David emphasizes: "You don't need dozens of MCPs, hundreds of pre-built skills, endless plugins. These four tools is all you need. Pi Agent is the clear proof."

The bash tool alone enables Pi to do anything a developer could do with full computer access: open files, manage packages, install software, create folders, open/close applications, analyze networks, and more.

5 Adding Web Access

▶ 9:59

Since Pi is minimal, web search isn't built in. Adding it is straightforward:

1. Go to pi.dev → Packages
2. Search for "pi web access" (90,000+ downloads/month)
3. Copy the install command and run it, or tell Pi to install it

The web search uses Exa and is free. David demos searching for "Elon Musk interview with Jamie Diamond" — results come back in seconds.

After installation, /reload loads the extension. On next launch, Pi shows the web access extension in its startup list.

Self-Improvement Philosophy

David's key point: use the agent to improve the agent. Don't do everything manually in the terminal. Tell Pi to install packages, rewrite prompts, set up skills — it can self-improve. "A lot of you are limiting the AI by your own limited prompts. This is not 2024 anymore."

6 The Four Ways to Improve Pi

▶ 12:46

David calls this the must-learn concept — what separates people who stop using Pi after two days from those whose Pi grows more powerful every day:

1. AGENTS.md — always-on context. Anything Pi should know every session goes here. Simplest to set up.
2. Prompt Templates — reusable slash commands for prompts you repeat often. Takes 30 seconds to create.
3. Skills — auto-loaded when relevant (like Claude skills). If you have a YouTube skill, Pi loads it when you discuss video creation. Takes 1–2 minutes.
4. Extensions — real TypeScript code. The most powerful but hardest to develop. Work as hooks. Best to use community extensions. Example: the Pi Web Access extension.

Each level is more powerful than the last, but also more complex. Most users will spend their time on AGENTS.md + prompt templates + skills.

7 Prompt Templates — Slash Commands

▶ 15:08

Prompt templates are Pi's version of slash commands. Any prompt you repeat more than once a day should become a template.

Creating a Template

David demos creating /review: just tell Pi "create a new prompt template called /review that does a deep review of the entire codebase" — Pi creates the template file. After /reload, the command works.

David's Favorite: /short

His most-used template: /short — makes responses simpler and shorter. Before this, he typed "make your answer simpler and shorter" 20–40 times per day. Now it's just /short + Tab + Enter.

"Every single minute is valuable. AI is advancing so fast that you cannot be typing the same prompts over and over. That's why prompt templates exist."

Important: /reload

After any config change (templates, skills, extensions, themes), run /reload to make it take effect immediately.

8 Skills — The Bread and Butter

▶ 18:11

David has 50+ skills — 85% custom-built, 15% from popular repositories. He calls skills "the bread and butter of Pi" and says he couldn't live without them.

Skills are stored in the global ~/.pi/agent/skills/ folder. Pi discovers them automatically and loads full content when the conversation matches a skill's topic.

Demo: Research Prompt Skill

David shows a "research prompt" skill that makes Pi optimized for writing deep research prompts. When he asks about "best meals before working out," Pi reads the skill (visible as a purple skill indicator) and generates a highly optimized research prompt ready to paste into ChatGPT 5.5 Pro Extended or Perplexity Deep Research.

The visual feedback is clear: when Pi loads a skill, you see a purple "skill" indicator in the output.

9 Steering Pi Mid-Run

▶ 21:41

Two methods to steer Pi while it's working:

• Enter — steers Pi immediately after the current tool call finishes. Use when you see it going down the wrong path: "No, that's not the folder I'm talking about"
• Alt/Option + Enter — queues a message to send after Pi finishes completely. You can queue 2–3 messages ahead of time. Great when you already know what's next.

David also shows Escape: press once to interrupt/stop generation, press twice to navigate the conversation history tree.

10 Slash Compact & the Status Bar

▶ 22:30

The /compact command compresses the conversation context — and it's blazing fast. David compacts in 2–3 seconds compared to Claude Code which takes a minute. He recommends compacting when you hit 30–50% context window usage.

The Status Bar

Pi's bottom status bar shows (left to right):

• Token information — input/output counts
• Session cost — current spending
• Context percentage — how full the context window is
• Auto-compaction status
• Model creator (e.g., Anthropic)
• Model name (e.g., Opus 4.8 Fast)
• Reasoning effort (changeable via Shift+Tab)

Everything is customizable — you can tell Pi to update its theme to show or hide any status element.

11 YOLO Mode & Permission Safety

▶ 25:24

Pi Agent is always in YOLO mode — it never asks for permissions. This is a design choice, not a bug. David is blunt: "It can easily delete a folder, delete a file, or install packages you don't want."

David's Recommendations

• Use the most powerful model possible — never use cheap models (Haiku, Gemini Flash) with Pi. Always use the latest Opus. Cheap models are far more likely to make catastrophic mistakes in YOLO mode
• Or install a permission system — search "permission" on pi.dev packages. The most popular is "Pi Permission System" (17,000 downloads/month). Install via pi install

David explains why this differs from Claude Code/Codex: those are products from trillion-dollar companies that can't risk an agent going rogue, so they heavily guardrail everything. Pi gives you the choice.

12 CMAX — The Multi-Agent Terminal

▶ 27:52

David reveals his actual daily setup: Pi Agent inside CMAX (an advanced terminal multiplexer built for AI agent management). He claims 90% of his AI interactions happen in CMAX with Pi.

CMAX Capabilities

• Multi-agent parallel execution — launch Pi, Claude Code, Codex, and more in a 2×2 grid in the same workspace
• Pane management — Cmd+D for horizontal split, Cmd+Shift+D for vertical, Cmd+N for new workspace
• Custom zoom per pane — large font for the main Pi you're talking to, small for background agents
• Built-in browser
• Pi can manage CMAX itself — it can read pane states, launch new panes, kill processes, send prompts to other agents

The Orchestration Pattern

Pi uses two skills to orchestrate: a CMAX skill (understanding the workspace layout) and a "delegating to agents" skill (sending tasks to other agents). In David's demo, Pi automatically analyzed the CMAX workspace, found four agent instances, and delegated tasks to all of them without any manual intervention.

Pi Has No Built-in Sub-Agents — By Design

Instead of sub-agents, Mario Zechner (Pi's creator) recommends spawning multiple Pi instances in parallel via tmux or CMAX. David argues this is simpler, more transparent, and gives you full control — unlike Claude Code's sub-agents where "half the time you don't even know what the sub-agent is doing."

13 Pi + Codex CLI — The Best Combo

▶ 31:58

David's daily workflow and his top recommendation: Pi as orchestrator, Codex CLI as the coder.

How It Works

• Pi runs on the left pane (orchestrator, personal agent with all your context and preferences)
• Codex CLI instances run in a 2×2 grid on the right (actual code execution, powered by ChatGPT subscription)
• Pi launches Codex instances, sends them tasks, monitors their output via sleep + read cycles, and corrects them when needed
• Codex instances use /goal to work until a goal is achieved

Cost Efficiency

This combo is cost-efficient: Pi only spends a few tokens reading Codex outputs. All the heavy code generation runs on the ChatGPT Pro subscription you're already paying for. David describes the $100/month ChatGPT subscription as "probably the highest value $100 you can spend in all of AI."

Demo: Four Apps in Parallel

David demos having Pi launch four Codex instances, assign each a different HTML app to build, monitor progress, detect when they all built the same app (file conflict), correct them by creating separate subfolders, and verify — all without manual intervention. The result: timer, calculator, to-do list, and stopwatch apps, built in parallel at zero OpenRouter cost.

VPS Debugging Pattern

An advanced use case: Pi on your local machine can open a CMAX pane, SSH into a VPS, launch Codex CLI on the VPS, and manage it remotely. Useful for debugging Hermes Agent or OpenClaw instances — Pi reads Codex's output instantly (LLMs read ~100x faster than humans) and makes corrections.

14 Sessions — Tree-Based Conversation History

▶ 39:14

Pi's session system is its most advanced concept. Unlike linear chat histories (ChatGPT, Claude Code), Pi sessions are trees.

Branching

• Double-Escape — navigate to any previous point in conversation history
• From any past message, you can enter a new response which creates a branch
• Both the original and branched versions coexist — you can continue in either
• Compare it to Git worktrees — each change branches off

Key Session Commands

• /fork — splits a branch into its own session file. You select the fork point and continue from there in a completely new session
• /resume — browse and select from previous sessions (equivalent to "chat history" in other tools)
• /share — creates a GitHub Gist link with the full session. Shows your prompts and Pi's responses in a shareable web view. Great for team collaboration

Session files are portable JSONL — you can copy, share, or build tools against them.

15 Anti-MCP — CLI-First Philosophy

▶ 44:44

Pi's approach is anti-MCP. The entire 47-minute video doesn't mention MCP servers until this point — and that's by design.

Instead of connecting MCP servers directly, Pi serves them as CLI tools. Anything you want to do can be a CLI command that Pi executes via its built-in bash tool.

If You Really Need MCP

• MCP Border — exposes MCP calls as CLI commands that Pi can run via bash
• Pi MCP Adapter — community extension that skips MCP bloat, loads tools directly via a small proxy

But David's recommendation: "Usually it's just better to use direct terminal commands and CLI tools which Pi can natively execute without any issues."

🎯 Key Takeaways

🔗 Resources & Links

• Pi Agent (pi.dev) — official site, documentation, one-liner installer, and package registry
• Pi Agent GitHub Repository — source code and full documentation
• OpenRouter — multi-provider API for accessing any model with Pi

⏱ Timestamp Index