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

Author
Affiliation

Thomas Bartz-Beielstein

Bartz & Bartz GmbH

Published

October 22, 2026

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.

NoteConventions
  • $ 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, on http://localhost:8080).
  • The primary example model is qwen3-coder-30b-a3b-instruct (an MLX model, good at tool-calling); openai/gpt-oss-20b is 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.