Skip to content
Back to articles
pi-coding-agentclaude-codetutorialalternativeai-coding

Pi Coding Agent: The Minimalist Claude Code Alternative

Step-by-step tutorial for Pi, the open-source terminal coding agent: install it, connect any model, and see where it replaces (or doesn't) Claude Code.

11 min read

Pi Coding Agent: The Minimalist Claude Code Alternative

An open-source terminal coding agent, with four tools and a tiny system prompt. This tutorial shows how to install it, connect any model, and decide whether it replaces Claude Code in your workflow.

Context

You already use Claude Code. You know the loop: open the terminal, describe the task, the AI reads your files, edits, runs commands, and hands back the result. It works. But you may have felt what a lot of people feel after a few months: the tool grew. Every release shifts the system prompt, adds features, nudges the model's behavior, and workflows you had tuned stop behaving the same way.

Pi was born from exactly that frustration. It is an open-source terminal coding agent that makes the opposite bet: start minimal and let you build the rest. Instead of turning off features you don't use, you turn on only the ones you need.

This tutorial covers installation, connecting models, day-to-day usage, and an honest assessment of where Pi replaces Claude Code well for building apps with AI, and where it doesn't.

What Pi Is

Pi is a minimal terminal coding harness, described by its own documentation as a CLI for Claude and other models. It runs in your terminal, reads and writes files, executes shell commands, and holds a conversation with the model about your code. So far, like any coding agent.

The difference is the philosophy. Pi is open-source under the MIT license and was created by Mario Zechner, the same author behind libgdx, a widely used Java game framework. There is no SaaS account, no cloud dashboard, no remote "workspace." You install a command-line binary, point it at whatever model provider you like, and it sits in your terminal working on your project.

By default, Pi gives the model just four tools:

Tool What it does
read Reads files
write Creates or overwrites files
edit Modifies existing files
bash Runs shell commands

The creator's argument is blunt: for an effective coding agent, those four tools are all you need. Pi's system prompt is around a thousand tokens, against a much larger prompt in Claude Code. The reasoning is that frontier models have been heavily trained to operate as agents, and understand what a coding agent is without verbose instructions. Everything beyond the minimum (memory, sub-agents, MCP, themes, skills) comes in through extensions you choose.

Pi vs Claude Code: What Actually Changes

Before the walkthrough, it pays to understand what you gain and what you lose by switching. The comparison below is the most important part for deciding whether the migration makes sense for you.

Dimension Pi Claude Code
Models 15+ providers, switch mid-session Anthropic-focused
Default tools 4 (read, write, edit, bash) Larger built-in set
System prompt Minimal (~1,000 tokens) Substantially larger
Extensibility TypeScript modules + skills MCP + hooks + skills
Observability Fully visible, editable session Sub-agents work as a black box
Tool cost Free (you pay the model) Subscription + model usage
License Open-source (MIT) Proprietary

A few differences deserve explanation, because they change your day-to-day:

Observability. The creator's central critique of Claude Code is opacity. When Claude Code spawns a sub-agent, you can't see what it does inside. Pi bets the other way: the whole session is visible, and planning happens in markdown files you can read and edit alongside the AI.

Security model. Pi doesn't pretend to restrict malicious behavior. The creator's stance is honest: the moment an agent can write and run code, any prompt-level barrier is theater. In practice, Pi runs the tools without heavy approval layers by default. You either trust the agent or you isolate it in a container. We'll return to this, because it matters when you point the agent at serious code.

What isn't built in. Pi deliberately ships without to-do lists, plan mode, background bash, or MCP by default. The reasoning: models handle ephemeral state poorly (markdown in a file beats an internal list), plan mode hides sub-agents (planning in a file is more transparent), long-running processes want tmux (more control and debugging), and MCP servers consume 7% to 9% of the context window per session (CLI tools with a README are more token-efficient). All of this exists in Pi, but as an optional extension.

Real multi-provider. Pi was built directly on each provider's SDK, not on a generic layer. That enables the feature the creator considers essential: switching models mid-session, carrying the context along. You can start with a cheap model to draft and move to a stronger one to finish.

One concrete data point is worth noting: on benchmarks like Terminal-Bench 2.0, Pi performed competitively against Codex, Cursor, and Windsurf, suggesting the minimal approach delivers as much as the more sophisticated alternatives.

Tutorial: From Zero to Your First Session

From here it's hands-on. The commands below come from the official documentation at pi.dev.

Step 1: Install

The simplest path on Linux or macOS is the official installer:

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

If you prefer npm (which needs Node.js), the documentation uses this command:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

The --ignore-scripts flag disables dependency lifecycle scripts during installation. There are also pnpm and bun options. After installing, you run the agent by entering your project folder:

cd your-project
pi

Step 2: Connect a Model

Pi doesn't bring its own model. You connect yours, in one of two ways.

Option A, subscription (OAuth). Inside Pi, run /login and pick your provider. The documentation lists Claude Pro/Max, ChatGPT Plus/Pro, and GitHub Copilot. Tokens refresh on their own and are stored in ~/.pi/agent/auth.json. If you already pay for a Claude Max plan, this is where it becomes Pi's engine.

Option B, API key. Set the provider's environment variable before launching Pi:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Pi supports 15+ providers via API key, among them Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, Groq, Cerebras, xAI, and OpenRouter, plus clouds like Azure OpenAI, Amazon Bedrock, and Google Vertex AI. The variables follow each one's convention (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and so on).

Credential resolution order is predictable: first the --api-key flag on the command line, then auth.json, then environment variables, and finally custom provider keys.

Tip: if you never want to paste the key into the terminal, auth.json accepts three formats per field: the literal value, a reference to an environment variable, or a shell command prefixed with ! (handy for pulling the key from a secret manager).

Step 3: Your First Session

With the model connected, you just talk. A good first command, suggested by the documentation itself, is to ask Pi to orient itself in the project:

Summarize this repository and tell me how to run its checks.

Pi will use read to read the relevant files and bash to inspect the project, then hand back a summary. Essential interface shortcuts:

Shortcut Action
enter Send the message
shift+enter New line
escape or ctrl+c Interrupt the agent
alt+enter Queue a follow-up message while it works
ctrl+o Expand or collapse a tool's output

alt+enter is what enables real-time steering: you correct course without waiting for the agent to finish. If you change your mind mid-run, alt+up brings queued messages back into the editor.

Step 4: Give Context with AGENTS.md

Here is the equivalent of CLAUDE.md. Pi reads an AGENTS.md file at the project root with your instructions: code conventions, build and test commands, repository rules. It also loads a global ~/.pi/agent/AGENTS.md and searches parent directories up to the git root.

# at the project root
echo "# Project instructions" > AGENTS.md

After editing context files, run /reload inside Pi to reload without restarting.

Step 5: Switch Models Mid-Conversation

This is one of the practical differentiators. Without ending the session, you open the model selector with ctrl+l and pick another one. To cycle quickly through recent models, use ctrl+p (next) and shift+ctrl+p (previous). The conversation context goes with you, so you can draft with a cheap model and finish with a stronger one in the same session.

Step 6: Tree-Structured Sessions

Pi stores each session as a tree, not as a linear list. Each entry has an id and a parentId, and the current position marks the active leaf. That lets you explore different paths without losing what's already been discussed. Sessions live in ~/.pi/agent/sessions/, organized by working directory, as JSONL files.

The most useful session commands:

Command What it does
pi -c Continues the most recent session
pi -r Opens the session browser at startup
/tree Navigates the session tree and jumps to any point
/fork Creates a new session from an earlier message
/export [file] Exports the session to HTML
/share Uploads the session as a private GitHub gist, with a shareable link

When you go back to an earlier point via /tree and type something different, Pi creates a new branch. It's the natural way to try an approach, dislike it, and go back to try another without noise.

Step 7: Reuse Your Claude Code Skills

If you invested in Claude Code skills, you don't have to rebuild them. Pi reads skills in the same format (a folder with SKILL.md, with name and description frontmatter, plus optional scripts/, references/, and assets/). It discovers skills in several places, including ~/.pi/agent/skills/ and .pi/skills/ in the project.

To point directly at your existing Claude Code skills, add the directory to your settings:

{
  "skills": ["~/.claude/skills"]
}

Pi uses on-demand loading: at startup it only reads each skill's name and description, and loads the full content via read when the task matches. It's the same progressive disclosure principle you already know.

Replacing Claude Code to Build Apps: Does It Work?

This is the question that matters for anyone building apps with AI. The honest answer is: it depends on what you value.

To build an app, the flow in Pi is what you'd expect from any competent coding agent. You write an AGENTS.md with the stack and conventions, describe the feature, and the agent reads, writes, edits, and runs commands. Complex planning you do in markdown files that stay versioned and visible, instead of an opaque plan mode. To run the dev server or long-running processes, the recommendation is tmux, which gives real control and logs, instead of a hidden background bash.

Pi replaces Claude Code well if you:

  • Want full control and observability over what the agent does
  • Use, or want to use, several models and providers (including local or self-hosted models)
  • Are bothered by behavior shifting on every Claude Code release
  • Like assembling your own workflow from parts, instead of disabling what you don't use
  • Work on a regulated team that needs auditability and the ability to route agent traffic

You may be better off staying on Claude Code if you:

  • Want everything working out of the box, without assembling extensions
  • Prefer a desktop app or GUI: Pi is terminal-only
  • Depend on specific features of the Claude Code ecosystem
  • Are just starting out and want zero configuration

There are real trade-offs the comparison can't hide. The "trust or isolate" security model shifts the full responsibility to you: malicious content in a file or in a command's output can influence the agent through prompt injection. For serious projects, running Pi inside a container stops being optional. The unified API, like any layer that unifies different providers, has leaky abstractions. And assembling your workflow from extensions costs configuration time that Claude Code already delivers ready-made.

There is no perfect tool. Pi trades built-in convenience for control and transparency. If that's the trade you want, it replaces Claude Code very well.

Community Reception

Reception has been positive. On forums like Reddit and Hacker News, Pi became known as "the minimal one that doesn't get in your way," the idea of installing it, pointing it at a project, and starting to work without ceremony. Independent reviews echo the praise for the philosophy: you build the agent you want, instead of disabling features you don't use.

Around the minimal core, a community-maintained ecosystem of extensions has already grown, covering persistent cross-session memory, model and token status displays, multi-step task tracking, sub-agents, and MCP adapters. For those who don't want to research, there are even bundles that add dozens of skills and themes at once.

Maturity is still that of a young project compared to Claude Code: the ecosystem is smaller, extensions vary in polish, and part of what's native in Claude Code is something you install in Pi. It's worth coming in with that expectation.

In Practice

Quickstart to go from zero to Pi running in your project:

1. Install Pi

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

2. Enter the project and launch the agent

cd your-project
pi

3. Connect a model

Inside Pi, for a subscription:

/login

Or, for an API key, before launching Pi:

export ANTHROPIC_API_KEY=sk-ant-...

4. Create AGENTS.md with the project rules

echo "# Project instructions" > AGENTS.md

5. Reuse your Claude Code skills

Add to your settings in ~/.pi/agent/settings.json:

{
  "skills": ["~/.claude/skills"]
}

6. Work

Describe the task, use ctrl+l to switch models, and alt+enter to correct course while the agent works.

Tip: to run the dev server or any long-running process, open it inside a tmux session. Pi has no background bash by design, and tmux gives you real logs and control.

Conclusion

Pi is a clear bet: less is more. Four tools, a minimal system prompt, and everything left over you wire up yourself. For anyone tired of watching their coding agent change behavior on every update, that stability and transparency are worth a lot.

What you take from this tutorial:

  • Pi is an open-source terminal coding agent (MIT), installable in one command
  • It connects 15+ providers, by subscription (/login) or API key, with mid-session model switching
  • It uses AGENTS.md for context and reads your Claude Code skills without conversion
  • Tree-structured sessions let you branch and backtrack without losing context
  • It replaces Claude Code very well when you prioritize control, observability, and model flexibility, and less well when you want everything ready-made and zero configuration

The best way to decide is to test. Installation is one command, and it coexists with Claude Code without conflict: you can run both in the same project for a few days and see which one sticks.

References