Pi Agent Setup & Configuration Mastery
Install and configure Pi Agent (pi.dev) as a minimal, highly customizable local AI coding agent — connect it to OpenRouter for multi-model support, wire up web search, and tune context files so the agent adapts to your workflow rather than the reverse.
- 1. Install Pi globally: copy the one-liner curl command from pi.dev and run it in any terminal (~20 seconds).
- 2. Launch Pi by typing `pi` in the terminal; if not authenticated, type `/lo` to open the provider selection menu.
- 3. Choose a provider (e.g., OpenRouter): log in to openrouter.ai, add $5–$10 in credits, generate a new API key with a spending limit, paste it into Pi when prompted.
- 4. Verify the connection by sending a test message (e.g., 'say hi') and confirming a response.
- 5. Select your model with `/model` (e.g., Claude Opus 4.8 Fast); adjust thinking effort at any time with Shift+Tab cycling through off → minimal → low → medium → high → extra high.
- 6. Understand Pi's four built-in tools — read, write, edit, bash — and internalize that bash alone gives the agent full terminal control (file management, package installs, network analysis, etc.).
- 7. Tune global behavior by asking Pi to locate its global folder and edit the `append-system.md` file; add preferences such as language rules, date format, response conciseness, or 'always relay bash output in text'.
- 8. For project-specific context, navigate to the project folder and ask Pi to create an `agents.md` file with relevant context; Pi loads it automatically in that directory.
- 9. Add web search capability: run `pip install pi-web-access` (or ask Pi to check and install it) — the package receives 90k+ downloads/month and is the standard extension.
- 10. Use Pi itself to manage its own configuration and extensions — ask it to install packages, update context files, or scaffold new agents rather than doing everything manually.
Gotcha Do not touch `system.md` directly — it overrides the entire system prompt and can break default behaviors set by the maintainer. Use `append-system.md` instead to extend behavior safely. Also keep API keys private and set a spending cap on OpenRouter to avoid unexpected charges.
A CLAUDE.md build brief + README. Unzip it into an empty repo, open the folder with your coding agent, and tell it to read CLAUDE.md and plan before building. A derived starting point — verify against David Ondrej’s video.