How to use the Pi coding agent

To use Pi, install it, run pi in your project, connect a model with /login, and learn the session commands: /tree, /fork and /clone to try another approach, /compact when the history gets long. For scripts, pi -p runs once and prints the answer.

Pi is a minimal, extensible coding agent harness for the terminal. It ships with strong defaults and deliberately leaves out features such as sub-agents and plan mode: you add what you need, or install it as a package. The steps below follow Pi’s documentation.

1. Install Pi

Pi needs Node.js 22.19 or newer. On macOS and Linux:

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

Or with npm:

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

2. Start it and sign in

cd ~/code/my-app
pi

Run /login inside Pi to connect a subscription or an API key for a built-in provider. The startup header lists the instructions and resources Pi loaded, which is the quickest way to check it picked up what you expected.

3. Pick a model and how hard it thinks

From the command line, --model selects a model by exact or fuzzy name, and --provider limits the lookup to one provider.

4. Work in sessions

Pi saves every session. The commands that make that useful:

• /new starts a fresh session for a new task.
• /name gives the current session a name you will recognise later.
• /resume opens another saved session; pi --continue from the same folder resumes the most recent one.
• /tree, /fork and /clone let you explore another approach without losing the work you have.
• /compact reduces the conversation history sent to the model when a long session starts to slow down.
• /session shows the session’s file, ID, message count, token usage and cost.

Branching is Pi’s answer to a wrong turn: fork before a risky change, and if it goes badly, go back to the branch that worked.

5. Script it

pi -p "summarise the changes on this branch"
pi --mode json "list the failing tests"

-p runs the prompt once, prints the final reply and exits. --mode json streams JSONL events instead, for a program that wants to follow each step.

Give Pi production context

Pi works from your repository. It can read the code that failed, but not the logs, traces and deploys that show how it failed. Polylane gives Pi that context: it connects to the platforms you already run on, so Pi can see when something breaks there.

Using Pi? See how to give Pi production context with Polylane.