Quick Start

This chapter gets Pi running locally: install dependencies, build, launch the coding agent, and understand the call chain of a minimal run. By the end you will have a working coding agent in your terminal and a clear picture of how a single request travels through Pi's layers. The whole flow is designed to be safe by default — pinned dependencies, disabled install scripts, and a recorded session you can audit after the fact.

Prerequisites

• Node.js 18+ and the bundled npm. Older versions may fail to build or run some packages.
• Git, to clone the monorepo.
• A model API key (optional for a first smoke test). Without a key you can still run with MockModel; with a key the agent can actually call an LLM.
• A sandbox (optional but recommended): Gondolin, Docker or OpenShell, to isolate what the agent is allowed to execute.

1. Get the source

Clone the repository and step into it. Pi is a single npm-workspaces monorepo, so one clone gives you every package.

git clone https://github.com/earendil-works/pi.git
cd pi

2. Install dependencies safely

Pi uses an npm workspaces monorepo. To avoid lifecycle scripts from untrusted dependencies executing code, the official recommendation is to always pass --ignore-scripts:

# dev install
npm install --ignore-scripts

# CI install
npm ci --ignore-scripts

3. Build & check

Build every package in the workspace, then optionally run the check suite (lint + format + type-check) to confirm your environment is healthy.

npm run build   # build all packages
npm run check   # lint + format + type-check

4. Launch the coding-agent CLI

pi-coding-agent is the interactive coding agent. From inside a repo you can ask it to read code, edit files and run commands like a pair programmer:

# run from source (callable from any directory)
./pi-test.sh

# run tests (auto-skips LLM-dependent cases without an API key)
./test.sh

When the prompt appears, try a small, concrete instruction first — for example, "summarize what this repository does in one sentence" — so you can confirm the model connection before attempting edits.

What you get: a terminal interface where every change the agent proposes is shown as a diff before it is written, every command it runs is visible, and the whole interaction is recorded so you can review or replay it later. Treat it like a very fast junior engineer: give precise instructions, check the diff, and keep the sandbox on.

5. Minimal agent loop

Pi's core is a stable loop: prepare context → call model → handle tool → write back → continue or stop. Here is a sketch of the call chain:

UI      → POST /api/runs
API     → returns runId, opens an SSE event stream
Session → writes the user message, builds context
Loop    → model.complete(messages, tools)
Model   → returns toolCall: read_file
Tool    → executes and returns the result
Loop    → calls the model again, until the final answer
API     → SSE pushes AgentEvent + the full session

Troubleshooting

• Build fails: confirm Node is 18+ with node -v, and that you used --ignore-scripts (a missing script can leave a package unbuilt).
• Agent replies it has no model: your API key env var is not set or not exported in the shell that launched ./pi-test.sh. Re-export it and restart.
• Want to test without a key: select MockModel; the core loop and tool logic run locally and cost nothing.
• Permission errors: run the agent inside a sandbox (Gondolin / Docker / OpenShell) so file and command access is bounded.
• Slow first run: the initial build compiles every workspace package; later builds are incremental and much faster.

Tips for daily use

• Be specific. Name the file and the behavior you want; small, single-goal requests produce smaller, easier-to-review diffs.
• Let it test. Ask the agent to run the test suite after a change so failures surface immediately.
• Keep history. The JSONL session tree lets you branch from any point, so don't be afraid to experiment.
• Stay offline-friendly. Use MockModel for structural work that does not need a real model.

From the CLI to your own agent

The CLI is convenient, but Pi is a toolkit you can embed. The smallest useful agent is just: define a tool, create a model, build an Agent, open a Session, and iterate on the events it emits. The Chinese first-agent tutorial shows the full TypeScript example; the Core packages page lists what each package exports.

Next steps

• For the overall design, go to Architecture.
• For package responsibilities, go to Core packages.
• For local debugging and the permission model, go to Running & debugging.
• To write your own minimal agent, see the Chinese first-agent tutorial.