Pi Coding Agent: Install, Configure Models, and Use It Safely

What Is the Pi Coding Agent?

Pi is a minimal, open-source terminal coding harness. Its design is less about shipping every agent feature and more about giving you a small core that you can reshape. The current project is maintained by Earendil, and the canonical package is @earendil-works/pi-coding-agent.

The official Pi site describes four ways to run it: an interactive terminal UI, print or JSON output for scripts, an RPC process, and an embeddable SDK. Sessions are stored as trees, so you can branch from an earlier point without copying a flat transcript.

The useful mental model is harness, not sealed assistant. If you want a preassembled agent with a fixed permission system and workflow, compare the broader options in our AI coding agent guide. Choose Pi when controlling the harness itself is part of the job.

What Pi Includes—and What It Leaves to You

Pi gives the model four tools by default: read, write, edit, and bash. Project instructions come from AGENTS.md; skills, extensions, prompt templates, and themes provide the customization layer. The small default tool set makes the execution loop easy to reason about, but it does not make the loop harmless.

Install Pi with the Current Package

The official installer is the shortest path. Package-manager installs use --ignore-scriptsbecause Pi does not need dependency lifecycle scripts for a normal global installation. This guide was verified with the Pi 0.85.1 npm package on September 7, 2026; that package requires Node.js 22.19 or newer.

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

# Or choose one package manager:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
bun add -g --ignore-scripts @earendil-works/pi-coding-agent

Start pi inside a repository, then use /login for a built-in provider. Use/model or Ctrl+L to select a model. Pi's model picker only exposes models for which it can resolve authentication, which matters when you add a custom provider next.

Configure a Custom Model Provider

Pi reads custom providers from ~/.pi/agent/models.json. According to the official custom-model documentation, a provider needs a base URL, a supported API format, and one or more model definitions. Authentication can come from /login, the CLI, or an environment-backedapiKey value.

Run Pi on Morph

Morph's public chat models expose an OpenAI-compatible Chat Completions endpoint and support tool calls, which is the interface Pi needs for its read, write, edit, and bash loop. The example below is generated from this repository's pricing and model constants, so the model ID, context window, and displayed costs stay tied to the product source of truth.

{
  "providers": {
    "morph": {
      "baseUrl": "https://api.morphllm.com/v1",
      "api": "openai-completions",
      "apiKey": "$MORPH_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "morph-glm53-744b",
          "name": "Morph GLM-5.3 744B",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 1048576,
          "maxTokens": 16384,
          "cost": {
            "input": 1,
            "output": 3.41,
            "cacheRead": 0.2,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

The model has a 1M-token context window, but this client configuration deliberately caps each response at 16,384 tokens. Pi treats maxTokens as a real provider output ceiling, not display metadata. Raise it only when a task needs longer individual responses and you have set an appropriate spend boundary.

Export the key, confirm that Pi can see the provider, and select the model:

export MORPH_API_KEY="your-morph-api-key"

pi --list-models morph
pi --provider morph --model morph-glm53-744b

Pi is free to install under the MIT license, but requests to a hosted model are billed by that provider. Check the live Morph model catalog before adding another model; identifiers, context windows, and rates can change faster than this guide.

Verify the Setup Before Allowing Edits

First confirm that pi --list-models morph prints the configured model. Then run a read-only prompt in non-interactive JSON mode. This checks authentication, model resolution, tool calling, and repository access without asking Pi to change a file.

We ran this exact configuration against Pi 0.85.1 with both reasoning off and medium. In each run, Pi requested the built-in read tool, consumed its result, and completed the answer. No additionalcompat overrides were required for that tested package-and-endpoint pair.

pi --provider morph --model morph-glm53-744b   --thinking off   --tools read   --no-context-files   --no-extensions   --no-skills   --no-prompt-templates   --no-session   --mode json   -p "Use the read tool exactly once to read package.json, then answer with only the packageManager field."

Confirm the JSON event stream contains tool_execution_start andtool_execution_end for read, followed by agent_end. A prose answer alone does not prove that the tool loop worked. This test allows only the read tool and stores no session. It proves the basic API path, not that unattended work is safe. A disposable branch helps review and recover tracked changes, but it does not isolate credentials, untracked files, network access, or external systems. Use a container, VM, or restricted user as the security boundary, then inspect the diff and run the repository's checks before keeping an editing task.

Security and Troubleshooting

Pi has no built-in sandbox or permission popups. Its tools and extensions run with the same operating-system permissions as the Pi process. For unfamiliar repositories or prompts, use a container, a restricted user, or a permission extension. Treat an AGENTS.md file as executable guidance: read it before granting the agent access to credentials or production tooling. Pi's official security guidance explains this trust model.

Pi reloads models.json when you open /model, so you can correct configuration during a session. For the public model catalog and API behavior, use the Morph model documentation rather than copying rates or identifiers from a third-party post.

FAQ