Pi Coding Agent Tutorial 2026: Installation, Setup, Workflow & Common Pitfalls

Aug 11, 2026

Problem

I came from Claude Code and OpenCode. Both give me plan mode, sub-agents, MCP, and permission popups out of the box. So the first time I ran pi, I typed /plan and nothing happened. Then I typed /subagent and nothing happened. I checked the docs and found this:

no MCP
no sub-agents
no permission popups
no plan mode
no built-in to-dos
no background bash

I assumed Pi was incomplete. It is not. Pi is a minimal agent harness. It deliberately leaves those features out, and you build or install them when you need them. This post shows the install, setup, workflow, and the traps I hit along the way.

Information in this post is current as of August 2026. Verify commands against pi.dev and the earendil-works/pi repo before you publish anything.

Environment

macOS (also works on Linux)
Node.js available for the npm install path
One API key for at least one provider (Anthropic, OpenAI, Google, or any of 15+ others)

What happened?

1. Install

The one-liner worked for me:

curl -fsSL https://pi.dev/install.sh | sh

If you prefer a package manager, the npm route also works:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Verify with:

pi --version

2. Add a provider

Pi supports 15+ providers: Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, NVIDIA, OpenRouter, Ollama, and more. You authenticate with an API key or OAuth.

I set ANTHROPIC_API_KEY in my shell and Pi picked it up:

export ANTHROPIC_API_KEY="sk-ant-..."

Ollama works too if you run a local model, which is handy for testing without paying.

3. Start a session

Run pi inside a project directory:

cd ~/my-project
pi

You get an interactive TUI. Two key input behaviors matter:

Enter sends a steering message: it is delivered after the current tool and interrupts the remaining tools.
Alt+Enter sends a follow-up: it waits for the agent to finish before the next turn.

For non-interactive use:

pi -p "explain the build script in this repo"

The workflow I ended up with

Since there is no plan mode, I write plans to a file and let the agent read them. That gives me a reviewable artifact instead of a hidden planning step.

Here is the flow that works:

1. pi           start a session in the repo
2. AGENTS.md    loaded automatically from ~/.pi/agent/, parent dirs, current dir
3. /skill       load a skill on demand for the task
4. ask for a plan file
5. implement
6. Enter        steer mid-run when the agent goes off track
7. /model       switch provider/model when context gets heavy
8. /share       share the session tree as a gist

Let me unpack the useful pieces.

Model switching

/model switches provider or model mid-session. Ctrl+L is the keyboard shortcut. Ctrl+P cycles through your favorite models. I keep a cheap model for simple edits and a strong one for hard refactors, and switch without restarting.

Session tree

Sessions are stored as trees, and all branches live in one file. /tree jumps back to any earlier point. /export writes the session to HTML, and /share creates a gist URL. This is genuinely useful for reproducing a long debugging session.

Context control

Pi keeps a minimal system prompt and compacts older messages near the context limit. AGENTS.md is project instructions loaded into context from ~/.pi/agent/, parent directories, and the current directory. SYSTEM.md replaces or appends the default system prompt per project.

I found this is where Pi beats the tools that hide context management. You can see exactly what is in context, and extensions can inject messages, filter history, or build long-term memory.

Extensions and packages

Missing a feature? Build it as a TypeScript extension or install a package.

pi install npm:@foo/pi-plan-mode
pi install git:github.com/someone/pi-tools

The repo ships 50+ extension examples: subagents, plan-mode, permission-gate, protected-paths, ssh, sandbox. Extensions have access to tools, commands, keyboard shortcuts, events, and the full TUI.

Common pitfalls

This is the part I wish I had read first.

1. Assuming missing features are a bug

Plan mode, sub-agents, MCP, permission popups, and background bash are not built in. That is the design, not a defect. Check the extension examples before you file an issue.

2. Not knowing which capability needs an extension

Anything not in the core needs an extension or package. Make a list of what you rely on from your old agent, then map each item to an extension example. I mapped plan-mode, subagent, and permission-gate right away.

3. Ignoring the default permission model

There is no built-in permission system. Pi runs with the permissions of the user that launches it. That means a bad prompt can let the agent delete files or run arbitrary commands with your rights. Containerize or sandbox for risky work. The docs cover Gondolin, plain Docker, and OpenShell.

Pi runs with your user's permissions.
No permission popups. No sandbox by default.
Containerize for anything dangerous.

4. Treating AGENTS.md as a hard rule

AGENTS.md is an instruction file loaded into context. It is not an enforced sandbox or a permission boundary. The model reads it as guidance, and it can be ignored under the right (or wrong) prompt.

5. Installing a pile of extensions on day one

I installed plan mode, subagents, and a sandbox extension on the first day and spent hours untangling them. Keep the vanilla core first. Add one package at a time, verify it, then move on.

The reason

I think the key reason Pi trips up people like me is a product philosophy mismatch. Claude Code, Codex, and OpenCode bundle features so you can work immediately. Pi optimizes for a small, auditable, MIT-licensed core and assumes you will adapt it to your workflow. That is a trade-off, not a bug. The features are deliberately excluded from the core, which keeps it readable and lets you own the pieces you actually use.

Recommended starting setup

Week 1: vanilla core + one provider
         learn /model, /tree, AGENTS.md, SYSTEM.md
Week 2: add one package that fixes your biggest pain
Week 3: add a permission-gate or sandbox for risky work

The permission-gate or a container should be the first thing you add if you plan to let Pi touch deployment or destructive commands.

Summary

In this post, I showed how to install Pi, add a provider, run a real coding workflow, and avoid the pitfalls that come from expecting it to behave like Claude Code or OpenCode. The key point is that Pi is a minimal agent harness: it does not ship plan mode, sub-agents, MCP, permission popups, or background bash, and you build or install them when you need them. Start vanilla, add one package at a time, and sandbox anything risky, because Pi runs with your user’s permissions.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!