Pi Coding Agent Setup Guide

pi-setup-guide.md

Pi Coding Agent Setup Guide

1. Install the Agent

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

2. Launching Pi

# Interactive REPL
pi

# One-off prompt
pi -p "your prompt here"

# Continue last session (sessions are tree-structured)
pi -c

Use pi --list-models to inspect available models, or pass your own provider/model (e.g., pi --provider openai --model gpt-4o). Export the appropriate API key (e.g., OPENAI_API_KEY) before launching Pi.

3. Configuration Files

Purpose	Global Location	Project Location	Notes
CLAUDE/AGENT instructions	~/.pi/agent/CLAUDE.md (or AGENTS.md)	parent dirs + cwd	All discovered files are concatenated automatically.
System prompt (replace)	~/.pi/agent/SYSTEM.md	.pi/SYSTEM.md	Use APPEND_SYSTEM.md to extend defaults.
Settings	~/.pi/agent/settings.json	.pi/settings.json	Project settings override global.

4. Built-in & Optional Tools

Default tools: read, write, edit, bash. Enable more (e.g., grep, find, ls) via:

pi --tools read,bash,edit,write,grep,find,ls

Disable all defaults with pi --no-tools if you need a locked-down run.

5. MCP Integration

1. Install the adapter extension

   pi install npm:pi-mcp-adapter

2. Create ~/.pi/agent/mcp.json

   {
     "settings": {
       "toolPrefix": "mcp",
       "idleTimeout": 10
     },
     "mcpServers": {
       "chrome-devtools": {
         "command": "npx",
         "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"],
         "lifecycle": "lazy"
       }
     }
   }

   Key options per server: command, args, url (for HTTP servers), lifecycle (lazy/eager/keep-alive), idleTimeout, directTools, debug, env. You can also import configs from other agents (cursor, claude-code, claude-desktop, vscode, windsurf, codex).
3. Chrome DevTools server

   start-chromium  # launches Chrome with remote debugging on 127.0.0.1:9222
   pi -p "use chrome devtools to navigate to example.com"

   The adapter proxies MCP tools via a compact ~200-token tool, so Pi doesn't need to load every tool definition up front.

6. Session & Headless Tips

• pi --session-dir <path> to relocate the session tree.
• pi --no-session for ephemeral runs.
• For headless browser testing: xvfb-run -a pi -p "your command" (or rely on start-chromium headless mode).

7. Extensions & Skills

• Install extensions from npm or git: pi install npm:package@version, list via pi list, upgrade via pi update.
• Popular picks: pi-mcp-adapter, safe-git, pi-cost-dashboard, pi-notify, checkpoint, pi-canvas.

Installing Skills with skill.sh

skill.sh is a universal skill installer for Pi, Claude Code, Goose, and Windsurf.

# Install a skill for Pi
skill.sh install pi https://raw.githubusercontent.com/user/repo/main/skill.md

It downloads the skill markdown and places it under ~/.pi/agent/skills/, handling any Pi-specific setup. Reuse the same skill definitions across agents for consistent capabilities.

8. Helpful Resources

• Pi repo: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent
• MCP adapter: https://github.com/nicobailon/pi-mcp-adapter
• Awesome Pi agent list: https://github.com/qualisero/awesome-pi-agent
• Blog post introduction: https://lucumr.pocoo.org/2026/1/31/pi/