Pi Coding Agent

Pi (npm @earendil-works/pi-coding-agent) is a small, fast terminal coding agent. It reads custom OpenAI-compatible providers from ~/.pi/agent/models.json, so pointing it at rapid-mlx is one provider block.

Quick start

Needs: Pi 1.1.0 (npm install -g @earendil-works/pi-coding-agent@1.1.0).

$ rapid-mlx serve qwen3.5-4b-4bit --port 8000
# In another terminal:
$ rapid-mlx agents pi --setup --yes
$ pi --print --no-session --provider rapid-mlx --model qwen3.5-4b-4bit \
    "Use the read tool to read README.md and report its title"

--provider and --model pin the local route even if Pi has other credentials. rapid-mlx agents pi --test runs the integration check.

Install

$ npm install -g @earendil-works/pi-coding-agent

Setup

$ rapid-mlx serve qwen3.5-4b-4bit

# in another terminal
$ rapid-mlx agents pi --setup --dry-run   # preview only
$ rapid-mlx agents pi --setup             # preview, confirm, write

--setup reads the model id and context window from the running server. It then:

• prints an exact diff of ~/.pi/agent/models.json (or $PI_CODING_AGENT_DIR/models.json)
• asks Apply this configuration? [y/N]. Pass --yes in scripts, because a non-interactive run without it writes nothing.
• copies an existing file to models.json.bak.<unix-time>
• writes atomically, owner-only (0600). If models.json is a symlink, it updates the file the link points to.
• refuses to write if the file changed between preview and confirmation
• checks the server's /health and /v1/models (skip this with --no-check)

Your other providers are kept. Under the rapid-mlx provider, models are merged by id, so models you added there yourself are kept too. The block it writes:

// ~/.pi/agent/models.json
{
  "providers": {
    "rapid-mlx": {
      "baseUrl": "http://localhost:8000/v1",
      "api": "openai-completions",
      "apiKey": "not-needed",
      "models": [
        {
          "id": "qwen3.5-4b-4bit",
          "name": "qwen3.5-4b-4bit (Rapid-MLX)",
          "contextWindow": 262144,
          "maxTokens": 8192,
          "input": ["text"],
          "reasoning": false
        }
      ]
    }
  }
}

id and contextWindow come from the running server. The values above are for qwen3.5-4b-4bit.

Run

$ pi                                                      # interactive
$ pi --print --no-session --provider rapid-mlx --model qwen3.5-4b-4bit "summarize this repo"

If rapid-mlx is the only provider pi has credentials for, no flags are needed. Otherwise see the first gotcha below. Recommended aliases (per rapid-mlx agents pi): qwen3.6-35b-4bit, qwen3.5-9b-4bit, qwen3-coder-30b-4bit. rapid-mlx start pi starts a recommended model and then runs the same setup.

Gotchas

• Other providers can win. If pi has other providers authenticated (its auth.json or provider env keys), it may default to one of them. Pick the local model with /model (Ctrl+S saves it as the default), or pass --provider rapid-mlx --model <id>.
• "reasoning": false is the setting we verified. pi then sends no reasoning preference, and rapid-mlx turns thinking off on tool turns. "reasoning": true (so pi's /thinking drives reasoning_effort) has not been verified.
• Keyed servers. The Rapid-MLX desktop app (and any server started with --api-key or RAPID_MLX_API_KEY) needs a key. Export RAPID_MLX_API_KEY before running setup and keep it exported when you run pi: setup writes "apiKey": "$RAPID_MLX_API_KEY" (pi expands $NAME in models.json), so the key itself is not stored in the file. Without the variable it writes "not-needed", as above.
• pi's own telemetry. PI_TELEMETRY=0 turns off pi's install/update telemetry and provider attribution headers. PI_OFFLINE=1 stops its catalog refreshes.

See also