# Pi Coding Agent Setup Guide

> Source: <https://gist.github.com/schpet/85531b6a05a5d8119e859bdec6b0e0b8>
> Published: 2026-02-04 18:00:42+00:00

# Pi Coding Agent Setup Guide

## 1. Install the Agent
```bash
npm install -g @mariozechner/pi-coding-agent
```

## 2. Launching Pi
```bash
# 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:
```bash
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**
   ```bash
   pi install npm:pi-mcp-adapter
   ```
2. **Create `~/.pi/agent/mcp.json`**
   ```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**
   ```bash
   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.
```bash
# 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/