Pi Coding Agent Setup Guide: Install, Configure Models, and Best Extensions

I have been running OpenCode and Hermes Agent for a while now, but Pi kept coming up in conversations. People on Reddit and Hacker News kept calling it “the minimal one that does not get in your way.” After two weeks of daily use, I see why. Pi is a terminal coding agent built by Mario Zechner that stays small at the core. You install it, point it at a project, and start working. Everything else — memory, MCP support, sub-agents, themes, skills — gets added through extensions you actually choose.

That minimalism is the point. Where OpenCode ships with a TUI, plan mode, and image support out of the box, Pi gives you a clean slate and a TypeScript extension system. You build the agent you want instead of disabling the features you do not need.

Below you will find installation steps, model configuration with cheap providers, the extensions I actually use, and how to skip the research phase with LazyPi.

If you are still deciding between coding agents, our OpenCode setup guide covers the open-source Claude Code alternative, and the GitHub Copilot alternatives article breaks down what to do after the June 1 pricing change.

What Pi actually is

Pi is a terminal coding agent that reads your codebase, plans changes, edits files, runs shell commands, and iterates on failures. The default installation gives you four tools: read, write, edit, and bash. That is it. No plan mode, no MCP support, no memory, no sub-agents. You add those through extensions.

The extension system is TypeScript. You drop a .ts file into ~/.pi/agent/extensions/ and Pi loads it. Extensions can register custom tools the LLM can call, intercept tool calls before they execute (to block rm -rf for example), add slash commands, modify the system prompt, and build custom TUI components. You can hot-reload them with /reload without restarting Pi.

Installing Pi

Pi is distributed as an npm package.

npm install -g @mariozechner/pi-coding-agent

Then run it in a project directory:

cd /path/to/project
pi

Pi needs Node.js 18+. If you do not have Node, install it first:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

docker run -it --rm -v $(pwd):/workspace -w /workspace node:22 \
  npx @mariozechner/pi-coding-agent

Authenticate

Pi supports two authentication approaches. Pick whichever fits.

Subscription login — if you have Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, or Google Gemini CLI:

pi
/login
# Select your provider

API key — for direct provider access or OpenRouter:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Or store keys in ~/.pi/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openrouter": { "type": "api_key", "key": "sk-or-..." }
}

Auth file entries take priority over environment variables.

Configuring models

This is where Pi gets interesting. You can connect to any model provider through environment variables, the auth file, or a custom models.json file.

Using built-in providers

Pi has built-in support for these providers:

Set the key and Pi auto-discovers all models for that provider:

export OPENROUTER_API_KEY=sk-or-...
pi
# /model shows all 200+ OpenRouter models

Adding custom models with models.json

For providers that are not built-in — or for Ollama, LM Studio, vLLM, and any OpenAI-compatible API — create ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

The apiKey field is required but Ollama ignores it, so any string works. The file reloads each time you open /model, so you can edit it during a session without restarting Pi.

For local models that do not support the developer role used by reasoning models, add compatibility flags:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "qwen3.6:27b",
          "reasoning": true
        }
      ]
    }
  }
}

Connecting to OpenRouter for cheap models

OpenRouter is the easiest way to get access to all the affordable models in one place. Set your key:

export OPENROUTER_API_KEY=sk-or-...

Then use /model in Pi to pick from the full list. The models I keep using:

For a full breakdown of these models with benchmarks and pricing, see the best cheap models for Hermes Agent guide — the same models work with Pi.

Using OpenCode Go with Pi

OpenCode Go is a $10/month subscription that bundles 12 models including MiniMax M2.7, Qwen 3.6 Plus, GLM 5.1, DeepSeek V4 Pro, and Kimi K2.6. Pi supports it as a built-in provider. For a detailed look at limits and benchmarks, see the OpenCode Go guide.

export OPENCODE_API_KEY=your-opencode-go-key
pi
# /model, select opencode-go provider

What OpenCode Go includes

The current lineup has 12 models:

The list changes as the OpenCode team tests and benchmarks new models. They do not add every open source model. Each one gets tested for coding agent use and the teams work with model providers to optimize the service.

Usage limits

Go is not unlimited. It uses dollar-value limits, not request counts:

Cheaper models stretch further. With DeepSeek V4 Flash you get around 31,650 requests per 5 hours. With GLM 5.1 you get around 880. In practice, the limits are generous enough for daily coding work — I have not hit them once in three weeks of use.

If you have credits in your OpenCode Zen balance, you can enable the “Use balance” option in the console. When Go limits run out, it falls back to your Zen balance instead of blocking requests.

How it compares to managing your own keys

With separate API keys, you pay per token and track billing across multiple providers. My monthly cost with direct API keys was $15-20. Go at $10/month gives me access to the same models plus 10 more I would not have bothered setting up. The limits are generous enough that I have not hit them once.

The trade-off is control. With direct API keys, you can switch providers if one goes down. With Go, you depend on the OpenCode team for failover. In practice, I have had no downtime issues, but it is worth mentioning.

Overriding built-in provider URLs

If you want to route a built-in provider through a proxy, add a minimal entry to models.json:

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1"
    }
  }
}

All built-in Anthropic models remain available. Existing auth continues to work.

Project instructions with AGENTS.md

Pi loads context files at startup. Create an AGENTS.md file in your project root:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Use the existing error handling pattern in src/errors/.
- Keep responses concise.

Pi loads ~/.pi/agent/AGENTS.md for global instructions and AGENTS.md from parent directories and the current directory. Run /reload after changes.

Extensions worth installing

Extensions are where Pi becomes more than a basic agent. Here are the ones that make a real difference.

Extensions that make Pi smarter

pi-memory-md — Persistent memory stored as Markdown files. The agent remembers what it learned about your project across sessions. Without this, Pi starts fresh every time. This is the first extension I install.

pi-mcp-adapter — Connects Pi to any MCP-compatible tool server. GitHub, Playwright, Brave Search, Postgres, Notion, Slack — any MCP server works. If you use MCP with other agents like Hermes or OpenClaw, this lets you reuse the same tools.

pi-subagents — Run isolated sub-agents for parallel work. When a task has independent parts, sub-agents tackle them simultaneously instead of doing everything in sequence.

pi-plan — Read-only planning mode with approval-based execution. Like OpenCode’s Tab-to-switch plan mode. Pi describes what it would do, you review, then approve. Safer for production code.

Extensions that save you time

pi-web-access — Web search and URL fetching inside Pi. The agent can look up documentation, check Stack Overflow, or fetch API references without leaving the terminal.

pi-autoresearch — Long-running research loop. Tell Pi to research a topic and it iterates — searching, reading, summarizing, searching again — until it has a complete answer.

pi-simplify — Reviews recently changed code for clarity and consistency. After the agent makes changes, run this to catch style issues and dead code.

Extensions that improve the interface

pi-powerbar — Status line showing model name, token usage, and context status at a glance. Small thing that makes a big difference when you switch models often.

pi-usage-extension — Tracks token usage and API cost in-session. If you are trying to keep costs down with cheap models, this shows you exactly what each request costs.

pi-manage-todo-list — Multi-step work tracking with a live progress widget. Break a task into steps, track what is done, what is in progress, what is left.

pi-btw — Ask quick side questions without polluting the conversation history. Useful for “wait, what does this function do again?” without derailing your current task.

pi-add-dir — Load extra project directories into the current Pi session. If your work spans multiple repos, this lets Pi see all of them.

Installing extensions

Single-file extensions go directly in the extensions directory:

# Example: copy a single extension
cp ask-user-question.ts ~/.pi/agent/extensions/

Directory extensions:

# Copy the directory
cp -r pi-memory-md ~/.pi/agent/extensions/

# Install npm dependencies if the extension has a package.json
cd ~/.pi/agent/extensions/pi-memory-md
npm install

Then restart Pi or run /reload.

My Pi setup: what I actually install

After months of testing different combinations, here is the setup I run on every machine. These are the npm packages I install on top of vanilla Pi.

Required packages

pi install npm:pi-tinyfish
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:@juanibiapina/pi-powerbar
pi install npm:pi-hermes-memory
pi install npm:@juicesharp/rpiv-todo

Here is what each one does and why I keep it:

pi-tinyfish — Web search and URL fetching inside Pi. The agent can look up documentation, check API references, or fetch articles without leaving the terminal. This replaces the need to copy-paste URLs or switch to a browser mid-session. Search and Fetch are free — get your API key here.

@juicesharp/rpiv-ask-user-question — Structured question prompts during execution. Instead of the agent guessing when requirements are ambiguous, it asks you structured questions with 2-4 options. Keeps conversations focused and reduces back-and-forth.

@juanibiapina/pi-powerbar — Status line showing model name, token usage, and context status at a glance. Small thing that makes a big difference when you switch models often. I use multiple models throughout the day, so seeing which one is active saves mistakes.

pi-hermes-memory — Persistent memory stored across sessions. The agent remembers project conventions, your preferences, and past decisions. Without this, Pi starts fresh every time. This is the extension that makes Pi feel like it actually knows your codebase.

@juicesharp/rpiv-todo — Multi-step task tracking with a live progress widget. Break a task into steps, track what is done, what is in progress, what is left. Essential for any work that takes more than a few turns.

Optional packages

These two I install when I need them, but they are not part of my daily setup:

pi install npm:pi-subagents
pi install npm:pi-mcp-adapter

pi-subagents — Run isolated sub-agents for parallel work. Useful when a task has independent parts that can be tackled simultaneously. I install this for large refactoring sessions or when I need to work across multiple files in parallel.

pi-mcp-adapter — Connects Pi to any MCP-compatible tool server. GitHub, Playwright, Brave Search, Postgres, Notion, Slack — any MCP server works. I install this when I need to connect Pi to external services beyond what the other extensions provide.

Using OpenCode Go with your setup

Instead of managing separate API keys for each model provider, I use OpenCode Go. It is a $10/month subscription that bundles 12 models including MiniMax M2.7, Qwen 3.6 Plus, GLM 5.1, DeepSeek V4 Pro, and Kimi K2.6. Pi supports it as a built-in provider — you just set the API key:

export OPENCODE_API_KEY=your-opencode-go-key
pi
# /model, select opencode-go provider

That is it. No OpenRouter account, no separate billing, no tracking which key goes where. One key, 12 models, works in Pi and any other agent that speaks OpenAI-compatible APIs.

LazyPi: one command, everything configured

If you do not want to research and pick individual extensions, LazyPi does it for you.

npx @robzolkos/lazypi

This installs Pi if you do not have it, then adds:

You can install everything at once or use the interactive picker to choose specific packages. Re-running the command skips anything already installed.

The LazyPi catalog includes all the extensions listed above plus 60+ community skills and 76 terminal themes (Dracula, Nord, Gruvbox, Tokyo Night, Kanagawa, and more).

Community config: pi-config

The pi-config repository by amosblomqvist is a curated collection of personal Pi skills and extensions. It is not meant to be installed as one package — browse the repo and copy what you need.

What is in it

Extensions:

• bash-guard — blocks dangerous commands before they run
• context.ts — loads extra context from external sources
• filechanges — tracks file modifications across turns
• google-image-search — search Google Images from inside Pi
• memory.ts — another persistent memory implementation
• subagents — sub-agent support
• web-fetch — fetch and read web pages
• web-search — web search integration
• youtube-search — search YouTube from inside Pi
• video-extract — extract information from video URLs
• zz-read-only-mode — forces read-only mode (blocks all writes)

Skills:

• orchestrator — coordinates multi-step workflows
• pdf-reader — read and extract text from PDF files
• reddit — search and read Reddit posts
• stop-slop — prevents the agent from generating low-quality filler

How to use it

# Copy a single-file extension
cp extensions/ask-user-question.ts ~/.pi/agent/extensions/

# Copy a directory extension
cp -r extensions/web-fetch ~/.pi/agent/extensions/

# Install deps if needed
cd ~/.pi/agent/extensions/web-fetch
npm install

# Copy a skill
cp -r skills/reddit ~/.pi/agent/skills/

# Reload
# In Pi: /reload

Some extensions need system tools:

# For youtube-search and video-extract
brew install yt-dlp ffmpeg

# For pdf-reader
python3 -m venv ~/.pi/agent/skills/pdf-reader/.venv
~/.pi/agent/skills/pdf-reader/.venv/bin/pip install -r ~/.pi/agent/skills/pdf-reader/requirements.txt

pi_agent_rust: the Rust port

If you want the same agent concept but compiled to a single binary with faster startup and lower memory usage, there is pi_agent_rust.

What it is

A high-performance AI coding agent CLI written in Rust with zero unsafe code. 823 GitHub stars, 2,812 commits, 13 releases, and active development (the latest commit was hours ago at the time of writing). It is a from-scratch Rust implementation that supports the same seven built-in tools as Pi (read, write, edit, bash, grep, find, ls) plus Anthropic and OpenAI providers with streaming.

Why you might want it

• Single binary — no Node.js runtime needed. The release binary is under 8MB.
• Startup time — 12ms versus several hundred milliseconds for the Node.js version.
• Extension ecosystem — supports TypeScript extensions via a built-in QuickJS runtime, so existing Pi extensions work.
• Security — formal threat model, fuzz testing, forbid(unsafe_code), and 60+ pages of security documentation.
• Session management — SQLite-backed sessions with branching and tree navigation.

Installing pi_agent_rust

# One-line installer
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh | bash

Or build from source:

git clone https://github.com/Dicklesworthstone/pi_agent_rust.git
cd pi_agent_rust
cargo build --release
# Binary at target/release/pi

When to use the Rust port

The Rust port is best for people who want the fastest possible terminal agent, run on resource-constrained machines, or prefer a single binary distribution. The Node.js version has the larger extension ecosystem and more active community extension development. Both read the same models.json and auth.json files, so you can switch between them without reconfiguring.

Pi vs OpenCode vs Claude Code

Pi starts smaller but grows through extensions. If you want to build your own agent workflow from parts, Pi is the better foundation. If you want everything working out of the box, OpenCode gets you there faster.

Daily workflow tips

Switching models

Use /model or Ctrl+L to pick a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.

Referencing files

Type @ in the editor to fuzzy-search files, or pass them on the command line:

pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"

Running shell commands

Prefix with ! to run a command and send its output to the model:

!npm run test

Use !! to run a command without adding it to the context.

Sessions

Sessions save automatically. Continue your last session:

pi -c

Browse previous sessions:

pi -r

Inside Pi, use /resume, /new, /tree, /fork, and /clone to manage sessions.

Non-interactive mode

For one-shot prompts in scripts or CI:

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What is in this image?"

Use --mode json for structured output or --mode rpc for process integration.

Running Pi on a VPS

Pi works over SSH. I run it on a $6/month VPS and connect from my laptop.

# Use tmux so sessions survive disconnects
tmux new -s pi
cd /path/to/project
pi

Detach with Ctrl+B, D and reattach later with tmux attach -t pi.

For a better SSH experience, use mosh:

mosh user@your-vps-ip

FAQ

For more AI agent guides, check out the Hermes Agent setup guide, the OpenCode setup guide, and the best cheap models for any coding agent. For the GitHub Copilot pricing changes and what they mean for your workflow, see the Copilot alternatives article. For a side-by-side comparison of OpenCode and Pi, see the OpenCode vs Pi Agent comparison.