This written version of the video tutorial was generated by an LLM from the video transcript, and supervised by me, Alejandro.
Most AI coding agents are opinionated. They come with built-in sub-agents, plan modes, permission popups, background processes, and rigid workflows. You adapt to them.
Pi Agent flips this. It’s a minimal terminal harness. Four built-in tools. No bloat. But underneath? It’s aggressively extensible. You shape it to fit your workflow without ever touching its source code.
By the end of this tutorial, you’ll understand what Pi is, how it works, and why “minimalist” doesn’t mean “limited.”
What Is Pi Agent?
Pi is a minimal terminal coding harness. Not a monolithic IDE plugin. Not a chatbot wrapper. A harness that gives an LLM four tools to interact with your filesystem and shell — with you in control of every layer.
The philosophy is simple: adapt pi to your workflows, not the other way around, and you never have to fork or modify the internals to do it.
The Four Modes
Pi ships with four interaction modes:
| Mode | Flag | Use Case |
|---|---|---|
| Interactive | (default) | Daily coding, full TUI |
-p | One-shot scripts, CI/CD | |
| JSON | --mode json | Tool integrations, structured output |
| RPC | --mode rpc | Embedding in IDEs, custom UIs |
For this tutorial, we’re in Interactive mode — the full terminal UI experience.
Built-in Providers
Pi ships with over 25 providers: Anthropic, OpenAI, Google, DeepSeek, Groq, Mistral, Bedrock, Cloudflare, xAI, OpenRouter, and more. Plus subscription support: Claude Pro, ChatGPT Plus, GitHub Copilot.
You authenticate once, then switch models with a keystroke.
First 5 Minutes with Pi
Let’s get started. Install Pi with npm:
npm install -g @mariozechner/pi-coding-agent
Set your API key:
export ANTHROPIC_API_KEY=sk-ant-...
Navigate to a project and run:
cd /path/to/project
pi
The Startup Header
Watch the startup header when Pi launches. It shows:
- Loaded context files (
AGENTS.md) - Available prompt templates
- Skills and extensions
- Your current working directory
The footer displays:
- Current model
- Token usage
- Session name
Everything you need at a glance.
First Prompt: Code Review
Let’s ask Pi to review code:
Read the README and main entry file, then summarize what this project does and suggest one improvement.
Pi sends the prompt to the model. The model decides it needs context, so it calls read on the README, then the main source file. Watch the tool call expand — you can see every line it reads.
Ctrl+O toggles tool output. When you’re iterating fast, you might not care about the full file contents. Collapse it.
The model summarizes the project and suggests an actual, useful improvement. Not generic advice — specific to the code it just read.
Making an Edit
Now let’s make a change:
Add a comment block at the top of src/index.ts explaining the module's purpose based on the README.
Pi calls edit. Look at the diff view — green lines for additions. Pi uses exact text replacement, not fuzzy search-replace. It finds the exact old text, replaces it with the new text. No risk of mangling the file.
This is critical. Other agents might guess where to insert code. Pi asks the model to specify the exact old text and the exact new text. It’s the safest patch method.
Running a Command
Run the test suite and tell me if everything passes.
The bash tool runs npm test. The output streams in real time. If it’s over 50KB or 2000 lines, Pi truncates it automatically and tells the model where to find the full log.
The model sees the exit code and the output. If tests fail, it can read the failure, fix the code, and run again. It’s a genuine feedback loop.
Customization at a Glance
This is where Pi goes from “neat tool” to “irreplaceable part of your workflow.”
Switching Models
Ctrl+L opens the model selector. Pick any model from any provider you’ve authenticated with. Switch from Claude to GPT-4o, DeepSeek, or anything else — instantly.
Shift+Tab cycles thinking levels — off, minimal, low, medium, high, extra high. The editor border changes color to show the current level.
Thinking levels control how much the model reasons before responding. Higher = better reasoning, slower responses, more tokens.
Prompt Templates
Prompt templates are Markdown files that expand into full prompts. Type /review and it expands to a detailed code review prompt with your preferred checklist.
You define templates in ~/.pi/agent/prompts/ as Markdown files. Any template in that directory becomes a slash command. It’s like having a library of expert prompts on speed dial.
Skills
Skills are self-contained capability packages. Load one with:
/skill:brave-search Pi Agent documentation features
Pi loads the skill’s instructions on demand, runs the search script, and returns results.
Skills follow the Agent Skills standard, so skills from Claude Code or OpenAI Codex work here too. Progressive disclosure — only the description stays in context; the full instructions load when needed.
Themes
Themes are JSON files with 51 color tokens. Built-in dark and light themes, or build your own.
Hot reload is the killer feature: edit your custom theme file and Pi applies changes instantly. No restart. Iterate on colors in real time.
Context Files
Context files are the secret weapon. Write an AGENTS.md in your project root with conventions, common commands, safety rules — and Pi loads it automatically at startup.
Pi walks up from your working directory, loading every AGENTS.md it finds. Global conventions from ~/.pi/agent/AGENTS.md, project-specific ones from the repo root. All concatenated. The model knows your team’s standards before you type a word.
The Power of Minimalism + Extensions
Here’s the philosophy that makes Pi different. Four tools. read, write, edit, bash. That’s the whole runtime. No bloat. No feature creep.
But here’s the trick: every tool can write the next version of itself. You extend the tool from inside the tool.
Write Your Own Extension
Create an extension at ~/.pi/agent/extensions/auto-greet.ts that prints a welcome message whenever a new session starts. Use pi.on('session_start', ...) and print 'Welcome back!' to the console.
Pi uses its own write tool to create a TypeScript file. Run /reload, start a new session, and see “Welcome back!” — printed from code you just asked Pi to write. This is meta: the agent extended itself.
Permission Gate
Create an extension that asks for confirmation before running any bash command containing rm -rf or git push --force. Use pi.on('tool_call', ...) to intercept and show a confirmation dialog.
Now when you ask Pi to do something dangerous, it asks first. You built safety into the tool by telling the tool to add that check.
That’s the power of self-modification. The agent can write its own capabilities.
What Extensions Can Do
Extensions can do everything:
- Permission gates — confirm before
rm -rf,sudo, etc. - Git checkpointing — auto-stash before each turn
- Custom tools — register tools the LLM can call (e.g.,
deploy,lint,test) - Custom UI — replace the editor, add status bars, widgets, even games (Doom!)
- Custom compaction — summarize sessions your way
- Plan mode — build it as an extension if you want it
- Sub-agents — spawn Pi instances via tmux, or build your own
Yes, an extension replaced the editor with Doom. While the LLM thinks, you shoot demons. That’s the level of customization we’re talking about.
Pi Packages
Bundle extensions, skills, prompts, and themes into Pi packages and share them via npm or git:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi config
The community can install your workflow with one command.
Security note: Extensions run with your full system permissions. Review source code before installing third-party packages.
Sessions: Your Work Is Never Lost
Everything you do in Pi is saved automatically.
Quit with Ctrl+C twice or /quit. Later, continue the same session:
pi -c
pi -c continues the most recent session. Every message, every tool call, every edit — all preserved.
The Tree
But here’s where it gets powerful. Sessions aren’t linear. They’re trees. Every branch is an alternative path you explored.
Type /tree to navigate. Jump back to any point and try a completely different approach. All history stays in one JSONL file. No lost work. No “what if I had tried the other way.”
Ctrl+O cycles filters — default, no-tools, user-only, labeled-only, all. Label important turns as bookmarks. It’s version control for your thought process.
Recap
Pi Agent is four built-in tools. Infinite customization. Sessions that branch. A philosophy that puts you in control.
- Minimal core:
read,write,edit,bash - 25+ providers: Switch models with Ctrl+L
- Extensions: Add anything without touching source
- Sessions: Branch, persist, and never lose work
- Context files: AGENTS.md for project conventions
In the next video, we’re doing a complete crash course. I’ll demo every single feature Pi has — message queuing, compaction, custom providers, the full TUI, non-interactive modes, everything. It’s going to be a firehose of useful stuff.