# How to use the Pi coding agent

> How to use the Pi coding agent: install it, sign in with /login, pick a model, branch sessions with /tree and /fork, compact context and script it with -p.

Part 6 of [Using coding agents: Claude Code, Cursor, Codex and more](https://polylane.com/series/using-coding-agents/)

Canonical: https://polylane.com/learn/coding-agents/how-to-use-the-pi-coding-agent/

To use Pi, install it with the installer script or npm, run pi in your project and use /login to connect a subscription or API key. Choose a model with /model, branch a session with /tree, /fork or /clone to try another approach, and use /compact when the history grows. For scripts, pi -p runs once and prints the reply.

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](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent).

## 1. Install Pi

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

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

Or with npm:

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

## 2. Start it and sign in

```bash
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

| Command | What it does |
| --- | --- |
| `/model` | Select a model |
| `/thinking` | Select how much reasoning the current model uses |
| `/settings` | Change common preferences |
| `/logout` | Remove a provider's access |

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

```bash
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](/for/pi/): 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](https://polylane.com/for/pi/).

## Common questions

**What is Pi?**

A minimal, extensible coding agent harness for the terminal. It ships with strong defaults and leaves out features such as sub-agents and plan mode, which you can add yourself or install as packages.

**What does Pi need to run?**

Node.js 22.19 or newer. Install it with the installer script, or with npm as @earendil-works/pi-coding-agent.

**How do I resume a Pi session?**

Run pi --continue in the same folder to resume the most recent session, or /resume inside Pi to open another saved one.

**How do I try a different approach without losing my work?**

Use /tree, /fork or /clone. Each lets you explore another direction while the existing session stays intact.

**Can I run Pi from a script?**

Yes. pi -p runs the prompt once, prints the final reply and exits, and --mode json streams JSONL events instead.

## Sources

- [Pi coding agent (README)](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
- [Using Pi (Pi docs)](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/usage.md)
- [Pi CLI reference (Pi docs)](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/cli.md)

## About the author



## More in this series

[Using coding agents: Claude Code, Cursor, Codex and more](https://polylane.com/series/using-coding-agents/)

1. [How to use Claude Code: a practical guide](https://polylane.com/learn/coding-agents/how-to-use-claude-code/)
2. [How to add MCP servers to Cursor](https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-cursor/)
3. [How to use Codex CLI: install, AGENTS.md, MCP and exec](https://polylane.com/learn/coding-agents/how-to-use-codex-cli/)
4. [How to use OpenCode: install, plan and build, MCP](https://polylane.com/learn/coding-agents/how-to-use-opencode/)
5. [How to add MCP servers to GitHub Copilot in VS Code](https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-github-copilot/)
6. [How to use the Pi coding agent](https://polylane.com/learn/coding-agents/how-to-use-the-pi-coding-agent/)

Previous: [How to add MCP servers to GitHub Copilot in VS Code](https://polylane.com/learn/coding-agents/how-to-add-mcp-servers-to-github-copilot/)

Get started with one command: `curl -fsSL https://polylane.com/setup | bash` installs the CLI, connects your coding agents, and creates the account.