PI AGENT FULL COURSE: Master Pi Agent in 30 Minutes

Key Concepts

• PI Agent (pi.dev): A minimal, highly customizable, open-source AI agent designed for power users.
• Harness vs. Product: PI is a "harness" (minimalist, user-controlled) rather than a "product" (bloated, opinionated, mass-market like Claude Code or Cursor).
• Context Engineering: Managing AI behavior via system.md, append_system.md, and agents.md files.
• YOLO Mode: A default operational state where the agent executes commands without asking for permission, requiring high-quality models to prevent errors.
• Orchestration: Using PI as a central controller to manage other agents (e.g., Codex CLI) within a terminal multiplexer like CMAX.
• Session Trees: A non-linear history management system allowing for branching, forking, and resuming complex workflows.

---

1. Installation and Setup

• Installation: Use the one-liner curl command from pi.dev in your terminal to install PI globally.
• Authentication: Launch via the pi command. Use /login to select a provider (e.g., OpenRouter).
• API Keys: Create keys via OpenRouter, set a budget limit, and paste them into the terminal.
• Model Selection: Use /model to switch between thousands of available AI models.
• Thinking Effort: Toggle reasoning depth using Shift + Tab (Minimal to Extra High).

2. Context Engineering & Customization

PI relies on three specific Markdown files to define its behavior:

1. system.md: Overrides the entire system prompt (use with caution).
2. append_system.md: Appends instructions to the default prompt (recommended for personal preferences like date formats or language constraints).
3. agents.md: Project-specific context that loads automatically when working within a specific directory.

3. The Four Pillars of PI Improvement

To evolve PI from a basic tool to a 10x productivity engine, users must master:

• agents.md: Persistent context for specific projects.
• Prompt Templates: Triggerable via / commands (e.g., /short to force concise responses).
• Skills: Modular tasks that auto-load when relevant (e.g., research prompts, web search).
• Extensions: TypeScript-based hooks for advanced functionality (e.g., pi-web-access).

4. Advanced Workflows: The CMAX Orchestrator

The instructor advocates for using CMAX (a terminal multiplexer) to manage multiple agents:

• Parallelism: Run multiple PI or Codex instances in a grid layout.
• Delegation: Use PI as an "orchestrator" that monitors and assigns tasks to other agents (e.g., Codex CLI) without the user needing to manually read every output.
• Efficiency: This setup reduces token costs by using PI to manage the logic while offloading heavy coding tasks to specialized agents.

5. Session Management

• Non-Linear History: PI treats conversations as a tree. You can navigate back to any point in the history using Escape twice and branch off into a new direction.
• /fork: Manually splits a branch into a new, independent session.
• /share: Generates a URL/Gist of the session, allowing team members to review the exact prompt-response history.
• /resume: Lists and reloads previous sessions, ensuring no work is lost after a restart.

6. Safety and Permissions

• YOLO Mode: PI operates without guardrails. The instructor emphasizes that this is a "skill issue" rather than a flaw; users should mitigate risk by using high-intelligence models (e.g., Claude Opus) rather than cheap, small models.
• Permission System: For those requiring safety, the pi-permission-system package can be installed to force approval for tool calls.

7. Notable Quotes

• "You should adapt PI to your workflows, not the other way around."
• "Stop trying to figure out everything yourself. Stop trying to be the bottleneck. Tell the agent to change the user interface... whatever you want, it can do it."
• "Most people are just watchers. They go through life. They don't implement anything. Don't be one of them. Be a doer."

Synthesis

PI Agent represents a shift toward "agentic engineering," where the user acts as an architect rather than a manual operator. By leveraging a minimal core, modular skills, and a tree-based session structure, users can build a highly personalized AI environment. The most effective workflow involves using PI as an orchestrator within a terminal multiplexer (CMAX) to manage specialized coding agents, effectively automating complex development tasks while maintaining full control over the process.