Pi Agent – Crash Course | Minimal Coding Agent

◉ Overview

Alejandro AO walks through the Pi Agent harness from first install to full customization. Pi is a deliberately minimalist coding agent that ships with only four tools — read, write, edit, and bash — and asks you to build every other feature yourself. This crash course covers model switching, prompt templates, skills, themes, context files, the TypeScript extension system, community packages, and Pi's standout session management with tree-based history navigation and HTML export.

1 What Is Pi Agent

▶ 0:51

Pi is described as a minimalist agent harness that grows with you. Out of the box it ships with exactly four tools: read, write, edit, and bash. Alejandro contrasts this with "bloated" harnesses that ship everything built-in.

What Pi does NOT include by default

• No MCP support — but you can ask Pi to enable it via an extension
• No sub-agent support — add it yourself if needed
• No permission pop-ups — Pi runs commands freely. You can build a permission guard extension (demonstrated later in the video)
• No plan mode — write plans to files or implement plan mode via extensions
• No built-in to-dos — use a todo.md file instead, or build a to-do tracker

2 Installation

▶ 2:10

Installation is a single command. After installing, running pi brings up the terminal interface immediately. It auto-loads any skills found in the .agents directory.

First-time setup: adding a model provider

A freshly installed Pi has no models configured. You need to log in with either:

• API key — HuggingFace, OpenAI, etc.
• Subscription — ChatGPT, GitHub Copilot

Alejandro notes that Anthropic has discontinued third-party harness support, but ChatGPT and Copilot subscriptions still work. In this demo he uses HuggingFace inference providers, giving him access to models like Qwen, MiniMax, DeepSeek, and Kimi.

3 Switching Models

▶ 3:46

Pi offers two model browsing scopes:

• All — every model available from your configured providers
• Scoped (favorites) — a curated list you configure via /scoped-models

Keyboard shortcuts for fast switching

• Ctrl+P — quick-switch between scoped (favorite) models
• Shift+Tab — cycle through thinking levels (minimal, low, medium, high) for models that support extended thinking

Alejandro demonstrates switching instantly between GLM, DeepSeek, MiniMax, and Kimi using Ctrl+P, and adjusting thinking levels per model with Shift+Tab.

4 Custom Prompt Templates

▶ 5:28

Prompt templates are custom slash commands that expand into full prompts. Instead of typing the same detailed prompt repeatedly, you create a template once and invoke it with a slash command.

Creating a prompt template

Alejandro asks Pi itself to create a code review prompt: "Create a custom prompt for code review. Make it detailed and very thorough." Pi reads its own documentation, creates the prompt template file, and registers the new /code-review slash command.

Key details

• Templates are stored in ~/.pi/agent/prompts/
• After creating or modifying a prompt, you must reload Pi (use /reload or restart)
• Templates support variables for dynamic content
• You can copy existing prompts from Claude Code or other harnesses directly into the prompts directory

5 Skills

▶ 8:05

Skills in Pi work similarly to Claude Code or Codex skills. They are loaded from multiple discovery locations:

• ~/.agents/skills/ — shared cross-agent skills directory
• ~/.claude/ directory — Claude Code compatibility
• ~/.pi/agent/skills/ — Pi-specific global skills
• .pi/skills/ — workspace-local skills

Using skills

Type /skill and select from the loaded skills list. Alejandro demonstrates a custom "Skill Visualizer" — a tool he built that generates an HTML visualization of all available skills, their scripts, and references.

Running bash commands inline

• ! (single exclamation) — runs a bash command and adds it to conversation history (the agent sees it)
• !! (double exclamation) — runs a bash command silently, NOT added to history (doesn't clutter context)

6 Themes

▶ 11:26

Pi ships with just two themes: dark and light. The entire TUI is customizable — you can modify any aspect of the terminal interface.

Creating custom themes

Alejandro asks Pi to create a theme directly: "Create a fun theme for Pi agent right here in this workspace. Make it fun, make it creative." Pi generates a "Gummies" theme with custom colors for text, thinking indicators, and UI elements.

• Themes are stored in the themes/ directory
• Workspace-local themes go in .pi/themes/
• Apply via Settings → Themes
• After creating a theme, run /reload to pick it up

7 Context Files

▶ 13:17

Pi follows the AGENTS.md standard and also reads CLAUDE.md files for compatibility. Both are loaded and concatenated into the system prompt.

How context files are discovered

• Workspace-level: AGENTS.md and CLAUDE.md in your project directory
• Home-level: ~/.claude/CLAUDE.md (global instructions)
• Pi reads all of them and adds them to context — they're additive, not exclusive

This means if you're already using Claude Code or another agent with AGENTS.md or CLAUDE.md files, Pi picks them up automatically with zero additional configuration.

8 Extensions

▶ 15:13

Extensions are the core mechanism for making Pi do more. They're TypeScript files that extend Pi's functionality — from adding UI elements to creating entirely new tool capabilities.

Demo 1: Welcome Quote Extension

Alejandro asks Pi to "create an extension that prints a welcome message whenever a new session starts. Write a set of messages that are quotes from famous scientists and writers and each time display one randomly."

After restarting Pi, a random quote appears at the top of every new session: "Logic will take you from A to B, imagination will take you everywhere." — Albert Einstein

Demo 2: Dangerous Command Guard

The more practical example: an extension that asks for confirmation before running any bash command containing rm -rf or git push --force.

• Alejandro creates the extension, restarts Pi, and tests by asking it to delete a directory
• Pi now shows: "Dangerous command detected: RM with force recursive flags. Execute anyway? Yes/No"
• He then removes the extension and verifies that without it, Pi deletes without asking — confirming the extension was actually doing the work

Extension storage

• Global: ~/.pi/agent/extensions/
• Workspace-local: .pi/extensions/
• Extensions are plain TypeScript files — no compilation needed (loaded via jiti)

9 Packages

▶ 20:32

Packages are bundles of extensions, skills, and prompts that work together as a cohesive unit. They're installable with a single command and provided by community contributors.

Available community packages

• pi-subagents — adds sub-agent spawning capability
• context-mode — context management features
• MCP Adapter — Model Context Protocol support
• Web Search — web search capability (Pi has no built-in search)
• pi-web-access — web browsing and access

All packages are open source. Alejandro emphasizes reviewing packages before installing — they can contain scripts that your agent will execute, so you should verify they're safe (or at least have Pi review them for you).

10 Sessions

▶ 22:02

Alejandro calls this his favorite Pi feature. Sessions provide full conversation history management with tree-based navigation.

Session management commands

• /name — rename the current session
• /session — view session info including file location
• /tree — display the full conversation tree for navigation
• /fork — duplicate the session and continue on the copy
• /clone — duplicate at the current position
• /compact — compress the conversation when approaching context limits, with optional custom instructions (e.g., "pay attention to the API")
• /export — export the session as an HTML file

Tree-based history navigation

If you send a message and realize it was wrong, you can use /tree to view all messages, navigate back to any previous point, and continue from there — like Git branches for conversations.

Session storage

Sessions are stored in ~/.pi/agent/sessions/, organized by the directory where each session was started. Each session is a JSONL file — making it easy to use sessions for training data, skill creation, or analysis.

HTML export

The /export command generates a polished HTML file with:

• All messages beautifully rendered
• A sidebar for navigation
• Filtering by: tools, user, labeled messages, or all
• A JSONL download button for raw data

🎯 Key Takeaways

🔗 Resources & Links

• pi.dev — Pi Agent official website
• earendil-works/pi — Pi Agent GitHub repository
• agentskills.io — Agent Skills standard (used by Pi for skill discovery)

⏱ Timestamp Index