Deep Dive: Pi School’s 15 Lessons — A Free Course That Teaches You Pi Agent Using Pi Itself, So Pi Teaches You While You Use It

The Pi School Course

Pi School is a free, self-paced, open-source course (Apache 2.0, a community project, not an official product) that teaches Pi (https://pi.dev/), a minimalist terminal coding agent run by Earendil Works. The course is clear about its positioning: Pi is a “model-agnostic” local agent whose core does the absolute minimum — reading and writing files, running commands, connecting to models — while everything else is assembled from Skills, Extensions, prompt templates, and MCP servers.

The course is explicit about its target audience: not just developers, but “anyone who wants to use AI to build creative things on their computer.” It only requires basic comfort with the command line, not programming skills. That said, the latter half (Code mode, Extensions) does leave room for depth aimed at seasoned developers.

Pedagogical Design: The Format Itself Demonstrates the Product Philosophy

The most notable thing about this course is that its delivery method is structurally isomorphic to the product’s philosophy:

• Lesson 1 is completed in the browser; the remaining 14 lessons are all conducted interactively inside the Pi terminal. Each lesson provides a single copy-paste prompt. You paste it to Pi, and Pi reads the lesson content, teaches you, and marks completion itself, with progress synced back to the web page in real time.

• In other words, there is no separation between “textbook” and “tool” — the tool is the instructor. Every step of learning Pi involves genuinely using Pi.

• Sign-up requires no account, collects no personal data, and generates a random student ID locally, with progress stored in Cloudflare KV. This lightweight, privacy-first stance is entirely consistent with Pi’s “minimal core” positioning.

This “learn X by using X” design carries an additional layer of implicit pedagogical value: it forces learners to treat AI agents as conversational collaborators from the very beginning, rather than as a piece of software requiring rote memorization of commands.

The Internal Arc of the 15 Lessons

On the surface the course covers 15 topics, but in reality it divides cleanly into four progressive stages.

Stage 1: Establishing the Environment and the “Contract” (Lessons 1–5)

Installation → Interview → Configuration → Trust → Instructions

This stage resolves three things: installing the tool, connecting to a model, and setting the ground rules.

• Installation takes a very pragmatic approach. Pi doesn’t bundle any free models, so the course provides a clear decision tree: if you have ChatGPT Plus/Pro, use the official “Sign in with ChatGPT” (an OpenAI-endorsed third-party access method); if not, sign up for a free OpenRouter account and pick a :free model at zero cost. What’s particularly noteworthy is its honesty: it explicitly warns that although Claude Pro/Max and GitHub Copilot appear in the /login options, routing their credentials through third-party tools violates Anthropic’s and GitHub’s terms of service, with a real history of account bans as enforcement — not recommended. This kind of “thoroughly explaining the terms-of-service risk” is rare among comparable tutorials.

• Interview is a personalization mechanism: Pi first asks whether you want the fast track (quick path, no quizzes) or thorough mode, and all questions are optional. One detail: fast track is the default — the course respects your time by default.

• Configuration introduces a two-tier configuration system: global ~/.pi/agent/settings.json and project-level .pi/settings.json (nested merge, project takes precedence), plus how to set a default model.

• Trust is the most important lesson of this stage, covered separately below.

• Instructions teaches AGENTS.md, which has become a de facto industry standard (used across Pi, Claude Code, and other tools), loaded across three tiers: global (personal preferences, not committed to Git), parent-directory chain, and project-level (committed to Git, shared with the team). The examples given are refreshingly grounded: not just coding standards, but also communication preferences like “never use em dashes” and “PR descriptions must start with ‘This PR’.” It also highlights a core Pi philosophy: Pi has no dedicated command like /init — you simply ask Pi in natural language to scan the project and generate AGENTS.md. “Describe what you want; Pi figures out how using the tools it already has.”

Stage 2: Understanding the Model’s Boundaries (Lessons 6–9)

Models → Context → Sessions → Branching

This stage shifts from “installed” to “understood,” and is the most cognitively dense part of the course.

• Models makes its core claim: model selection is the single biggest factor determining your Pi experience. Flagship models (Claude, GPT, Gemini) write better code, reason more strongly, and make fewer mistakes, but are billed per request. Free models cost nothing but are noticeably weaker on hard tasks. Using Pi well means finding the balance point between cost and capability. This lesson also covers Cloudflare AI Gateway / Workers AI as providers, as well as running local models via llama.cpp (free and private, but small models are clearly weaker at agentic tasks).

• Context covers context windows and compaction. This is general knowledge applicable to all AI tools: context is measured in tokens (roughly ¾ of a word each), and includes your messages, file contents, tool outputs, and the model’s replies. When the window is nearly full, Pi automatically triggers compaction, summarizing older parts of the conversation to free up space; you can also do it manually with /compact. The course’s practical advice is mature: with large models you don’t need to worry day-to-day; with small models, adopt a “one task, one session” discipline and watch for drift signals; the best time to proactively /compact is at task boundaries (summaries lose information, so compress less rather than more, and you can include instructions to guide what the summary focuses on, e.g. /compact focus on the API changes). It also carefully explains that the context meter at the bottom turning red is merely a color threshold (it only truly triggers around ~98%), not an error.

• Sessions covers session management: automatic saving as JSONL files, /new, /name, /resume, pi -c to continue the most recent session, the difference between /export (local HTML/JSONL) and /share (upload and generate a shareable view link), and /bug for generating private error reports.

• Branching is one of Pi’s most distinctive features: sessions are not linear message streams; they’re trees. Every entry has an id and parentId, and you can jump back to any historical node at any time via /tree. Selecting a user message puts it back in the editor for you to modify and re-send (creating a new branch); selecting an assistant message simply continues from that point. This solves two high-frequency pain points: comparing an alternative approach without losing your first attempt, and being able to roll back in place when you mess up instead of starting a new session. The course also disambiguates /tree (exploring within the same file), /fork (opening a new session from an earlier prompt), and /clone (copying the current branch).

Stage 3: The Capability Extension System (Lessons 10–15)

Skills → Tools → MCP → Code mode → Extensions → Images

This is the latter half of the course, covering how Pi grows from a “minimal core” into whatever you need it to be. It’s actually a four-layer extension model, shallow to deep:

1. Skills (knowledge packages), following the open standard initiated by Anthropic and now maintained by agentskills.io — essentially a folder containing a SKILL.md. They work on a “progressive disclosure” principle: only names and descriptions are loaded at startup; the full content is loaded only when needed. The recommended installation method is the npx skills CLI (installing once across all your AI tools). The course has students install four: Cloudflare, Replicate, frontend-design, and skill-creator — the last of which is used to “codify any workflow you’ve built into a reusable skill.”

2. MCP (external tool integration), the Model Context Protocol open standard. The four built-in tools by default (read/bash/edit/write) cover files and commands; everything else (real-time data, internal docs, third-party services) comes through MCP servers. The configuration format is identical to Claude Code/Cursor and can be copied over directly.

3. Code mode (batch execution), a clever design: instead of the model calling tools one by one, it writes a short JavaScript script that calls them in parallel (e.g. Promise.all to read ten files at once), and only the script’s result is returned to the model. The benefits are triple: fewer round trips, parallelism, and the ability to filter results before returning to save context. Scripts run in a sandbox with no file system and no network access — they can only do what Pi’s tools can do.

4. Extensions (behavior modification), the deepest layer: TypeScript modules that can subscribe to Pi’s lifecycle events, register custom tools and commands, and even build your own terminal UI. This is where the course calls out Pi’s philosophy directly: Pi has no Plan mode, no built-in per-action permission confirmation, no built-in web search. Features that “other tools have” in Pi are things you “write yourself as extensions” — the official distribution even ships plan-mode.ts and permission-gate.ts examples. This is what “minimal harness” means: the core guarantees extensibility and nothing more; it presupposes no behavior.

The interplay between MCP and Code mode is the finishing touch: MCP tools are not shown to the model directly by default (avoiding dozens of tool definitions eating up context) — instead, they are searched and invoked on demand through codemode scripts. Each server can be configured with one of four exposure levels: codemode / deferred / direct / hidden.

The final lesson, Images, wraps things up: four ways to feed images to the model — paste, drag-and-drop, @ reference, and CLI arguments — applicable to replicating UI designs, debugging visual bugs, and extracting text from screenshots. The prerequisite is that the model itself supports vision.

The Trust Model, Thorough

Trust deserves its own explanation, because it is Pi’s starkest philosophical divergence from other agent tools:

• Pi runs locally with your permissions and reads and writes files directly. Its only security gate is this: before loading any project-level configuration (.pi/settings.json, project MCP, extensions, skills, etc.), it requires your one-time explicit consent.

• It is not a per-action permission system. Once you’ve trusted a project, Pi will not pause for confirmation before every bash command or file edit the way some tools do. The course is unambiguous: if you want per-action confirmation, “it’s not a built-in setting — it’s an extension.”

• Trust decisions can be persisted via /trust into ~/.pi/agent/trust.json. You can set a global default with defaultProjectTrust: ask/always/never. Non-interactive modes (-p, --mode json/rpc) never prompt, and a single run can be overridden with --approve/-a.

• The decision criterion is also refreshingly plain: say yes for your own projects; say no for repos you just cloned and haven’t reviewed.

This is essentially a design stance that returns security responsibility to the user: a single high-leverage gate (configuration loading) guards against genuinely dangerous attack surfaces like “clone a malicious repo, get malicious config executed automatically,” while minimizing the friction of everyday operations.

Exercise Projects: From Course to Real-World Output

The 11 exercises are not homework problems — they are guided projects for completing real tasks with Pi, and their scope deliberately extends beyond “writing code”:

• Development-oriented: Building a personal homepage with Hono + Cloudflare Workers; unified billing routing with Cloudflare AI Gateway; a native macOS menu bar app that reads your own Pi usage stats via macos-app-skills.

• Media-oriented: Generating images and video with Replicate; cutting videos with FFMPEG + yt-dlp; local transcription with Whisper.

• Automation-oriented: Driving a real browser with Chrome DevTools skills; sorting a Gmail inbox; drafting social media posts with Typefully.

• Meta-learning-oriented: Using Matt Pocock’s teach skill to build custom courses in any domain for yourself.

• Engineering-fundamentals-oriented: Getting started with Git/GitHub and completing your first open-source contribution.

This selection of topics confirms the course’s ambition: Pi is not a “coding tool” — it’s a general-purpose computer agent.

Methodology from the Tips Page

Several plain but genuinely useful pieces of advice that reflect the author’s understanding of human-agent collaboration:

• Describe the goal, not the means (talk about the what, not the how) — leave the agent room to come up with a better approach.

• Know when to give up and start over. When you’ve fallen down a rabbit hole (agent makes a mistake → you correct it → it gets worse), decisively run /new or use /tree to go back to before things went wrong, rather than continuing to wrestle with it. This may be the skill beginners are most lacking.

• Directory is the permission boundary. Pi can only see what’s inside the directory level at which it was launched. To work across projects, launch from a higher level — but since there’s no sandbox, only do this in directories you trust.

• The course itself is flexible. You can ask it to skip lengthy explanations, have lessons taught in Spanish, and review your progress at any time. “Be silly. Be bossy.”

Overall Impressions

The strengths are concrete:

1. The course structure has a clear cognitive ladder: environment → model boundaries → the extension system. Each lesson builds on concepts from the previous one (e.g. the Code mode lesson circles back to the weather query from the MCP lesson, showing you’ve already been using codemode).

2. High honesty: it openly states that free models are weaker, openly flags which subscription paths violate terms of service with ban risks, and openly says “automatic compaction won’t notify you — the judgment call is yours.” It doesn’t dodge the tool’s limitations or trade-offs.

3. Betting on open standards over proprietary ecosystems: AGENTS.md, agentskills.io, MCP, the mcpServers format compatible with Claude/Cursor — most concepts learned here transfer to other tools.

4. It teaches mental models, not command lists: e.g. the compression heuristic of “compress less rather than more,” the branching tree’s “selecting a user message means editing the question, selecting an assistant message means continuing the answer,” and the trust model’s “one gate rather than a grid of rules” — all of these are transferable judgment frameworks. The Cheatsheet and Glossary pull out quick-reference needs separately, each serving its own purpose.

Limitations should be noted as well:

1. In terms of depth, this is an excellent introductory course, not an advanced one. The Extensions lesson only provides the API shape and pointers to 60+ examples; real extension development requires the official docs. For senior engineers, the most valuable material may only be the Pi-specific mechanisms of Trust / Branching / codemode.

2. Ecosystem lock-in isn’t light: 4 of the 11 exercises use Cloudflare products directly (the course itself also runs on Cloudflare), and services like Replicate and Typefully are specific commercial platforms. The workflows learned may transfer; the specific tools may not.

3. The course leans heavily on the “paste a prompt to Pi and have it teach you” model, which still poses a barrier for those not comfortable with pure terminal interaction. Additionally, the course content evolves alongside Pi versions (there are visible traces in the text like “the older version of the course installed pi-mcp-adapter”), so keeping it current remains an ongoing challenge.