Running pi Locally on Apple Silicon
A beginner’s guide to Mario Zechner’s minimal coding agent — local models via MLX and LM Studio, without the cloud
Preface
These notes are a hands-on, beginner-friendly guide to running pi, Mario Zechner’s deliberately minimal terminal AI (artificial intelligence) coding agent, against a local large language model (LLM) served by LM Studio or the MLX-LM server, on an Apple-Silicon Mac. The whole point is to drive a capable coding agent without sending your code or prompts to a cloud provider and without an API (application programming interface) key or subscription: the model runs on your own machine.
Everything in this book was verified on a real machine (an Apple M4 Max with 128 GB of unified memory running macOS, arm64) using pi 0.79.9, LM Studio with its lms command-line interface (CLI), and mlx-lm 0.31.3. When these notes were ported into the spotregen repository (2026-10-22), the current releases were pi 1.4.0 and mlx-lm 0.32.2; the commands were not re-run against those versions. Where a command or configuration is shown, it is the command that actually worked, and the troubleshooting chapter records what went wrong along the way.
Who this is for
You are comfortable in a terminal and have used Git, but you have no prior experience with pi and perhaps none with local LLMs. You do not need to know TypeScript (pi is written in it, but you will not write any). You do need a Mac with Apple Silicon: both backends in this book build on Apple’s MLX framework, which targets exactly that hardware.
What is pi, in one sentence?
pi is a small, transparent agent harness: it gives a language model exactly four tools (read, write, edit, and bash) and a short system prompt, then lets the model do the work in a loop. That is deliberately less than tools like Claude Code offer; 1 Introduction to PI explains why “less” is the point.
Roadmap through the chapters
The chapters follow the order you would actually take to get from zero to a working local coding agent.
| Chapter | You will… | Outcome |
|---|---|---|
| 01 | Understand what pi is and why it exists | The mental model |
| 02 | Install a local backend (MLX-LM or LM Studio), download a model | A local model server pi can talk to |
| 03 | Install the pi CLI | pi --version works |
| 04 | Point pi at your local model via ~/.pi/agent/models.json |
pi lists your local models |
| 05 | Run your first agentic session | pi writes & runs code locally |
| 06 | Steer pi with AGENTS.md / SYSTEM.md and use sessions |
Reproducible, project-aware runs |
| 07 | Drive pi headlessly via remote procedure call (RPC), its “server” mode | Programmatic and editor integration |
| 08 | Diagnose the common failure modes | A working, debuggable setup |
How to read these notes
Each chapter opens with a short learning-objective box and ends with a small set of exercises. Commands are shown in fenced blocks you can paste into your terminal; the agent-facing examples assume the local setup from chapters 02–04.
$at the start of a line denotes a shell prompt; do not type the$.- Local model commands assume LM Studio is serving on
http://localhost:1234(and the MLX server, where used, onhttp://localhost:8080). - The primary example model is
qwen3-coder-30b-a3b-instruct(an MLX model, good at tool-calling);openai/gpt-oss-20bis shown as a reasoning-model alternative.
A note on sources
pi is young and moving fast, so this book leans on primary sources: the pi repository and the docs bundled with the npm package, the author’s blog at https://mariozechner.at, the talk “Building pi in a World of Slop” (Zechner 2026), and the MLX-LM and LM Studio documentation. Academic background on agentic coding assistants and local inference is collected in the References.
Colophon
These notes are maintained inside the spotregen repository under docs/pi-documentation and are rendered with make pi-doc (HTML and PDF) from its Makefile. They are prose with displayed, non-executed command snippets, so no Python kernel is involved in the build.