Pi Coding Agent Review: Minimal, Hackable AI Coding CLI

Pi Coding Agent is a minimal, open-source terminal coding harness that ships with four default tools and leaves most of the behaviour to extensions, skills and your own workflow.

Most AI coding agents are becoming bigger products. They add planning modes, subagents, permission layers, IDE integrations, background workers and increasingly elaborate orchestration around the model. Pi takes almost the opposite approach: the default agent starts with four basic tools — read, write, edit and bash — while most of the interesting behaviour is deliberately left to extensions, skills, packages and your own workflow.

This review is aligned with Pi v0.84.2, released on 14 August 2026. Mario Zechner created the project; it moved to Earendil Works in May 2026, which is why current packages use the @earendil-works scope rather than the older @mariozechner names. Pi has been changing quickly, so configuration and extension APIs deserve a version check before you standardise them across a team.

The catch is equally important: Pi gives you considerably more control than many coding agents, and correspondingly more responsibility. It does not provide a built-in security sandbox or the kind of permission system developers may expect after using Claude Code or similar tools. Below I cover the quickstart, architecture, model support, extensions, session model, security implications and where I think Pi fits among modern AI coding tools.

What is Pi Coding Agent?

Pi is best understood as an agent harness rather than a finished, opinionated coding environment. That distinction matters: a coding model answers prompts, while an agent harness decides what context that model sees, which tools it can call, how tool results return to it, how sessions persist and what happens between turns. Pi makes almost all of those layers accessible, which is why it sits at the kit-building end of the AI developer tools field rather than among the batteries-included coding products.

The strongest reason to use Pi is not that it has more features than competing coding agents — it does not. The reason is that Pi exposes more of the agent itself. That makes it particularly attractive to senior developers, platform engineers, AI tooling teams and anyone who has reached the point where the limitations of their coding agent are caused by the harness rather than the underlying model. Pi is less convincing for someone who wants to install an agent, approve a few safe defaults and never think about its architecture again: its minimalism is productive only if you value the control that minimalism creates.

What Pi actually gives you

The default model-facing tool set is intentionally small:

read
write
edit
bash

Additional read-only tools including grep, find and ls are available, and recent Pi releases allow the initial built-in tool selection to be configured.

The default looks sparse, and that is the point. Every additional tool increases the number of decisions the model has to make, expands the system prompt and creates another behavioural surface that may need debugging. Pi instead starts from a capable primitive set and lets you add specialised tools when your workflow actually needs them.

The philosophy extends further than tools. Pi deliberately does not make built-in subagents or a mandatory plan mode central to the product; those behaviours can be implemented through extensions or installed packages instead. That makes Pi less convenient out of the box, but it gives developers more control over how those mechanisms are implemented. If you are used to Claude Code’s built-in subagents, the Claude Code subagents guide is a useful reference for what you would be reimplementing. I find that approach slightly refreshing: Pi does not pretend there is one correct way to operate an AI coding agent.

How to install Pi Coding Agent and start a session

Install the current package from the @earendil-works scope. Older tutorials may still show @mariozechner packages from before the May 2026 move; those names are stale for new installs.

The name also collides with oh-my-pi, a community fork of the Oh My Opencode harness. That project is unrelated to this coding agent; the Oh My Opencode review explains the fork if you landed on the wrong Pi.

Install and authenticate

1. Install Pi globally with npm:

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

   --ignore-scripts disables dependency lifecycle scripts during install. Pi does not need those scripts for a normal npm install, and skipping them reduces a common supply-chain risk.

2. Verify the installation:

   pi --version
   

3. Enter a project and start it:

   cd /path/to/project
   pi
   

Pi expects a bash-capable environment. On Windows, use WSL or Git Bash rather than cmd.exe.

Pi supports interactive subscription authentication as well as API-key based providers. Inside Pi, the simplest route is:

/login

After authentication, select a model with:

/model

You can also supply provider credentials through environment variables. For example:

export ANTHROPIC_API_KEY="your-api-key"
pi

Pi currently supports a broad collection of model providers, including OpenAI, Anthropic, Google, Azure OpenAI, Amazon Bedrock, NVIDIA NIM, DeepSeek, Mistral, Groq, Cerebras, Cloudflare, xAI, OpenRouter and several others. A llama.cpp router is also supported for locally served models: the llama.cpp quickstart covers serving GGUF models with an OpenAI-compatible API, and the LLM hosting guide maps the surrounding local, self-hosted and cloud runtimes if you want to compare that path with Ollama, vLLM or a hosted provider. Custom providers that speak a supported API can be added through ~/.pi/agent/models.json, and custom APIs or OAuth flows can be wired up with extensions.

This multi-provider design is one of Pi’s practical advantages. The model and the coding harness are separate variables: with Pi, you can change the model while keeping essentially the same tooling and session environment, which makes model comparisons considerably more meaningful than comparing completely different coding products.

Start with a controlled first session

I would not make your first Pi prompt “refactor my application”. Start by asking it to inspect rather than modify:

pi --tools read,grep,find,ls -p "Inspect this repository. Explain its architecture, identify the main entry points, and list the commands you would run before making a change. Do not modify files."

When I ran that read-only prompt on an existing repository, the useful result was not a clever architecture essay. It was whether the model named real entry points and the commands I would actually run before asking for write access. That gives you a look at how the selected model navigates your tree without immediately granting it a write path through the normal tool set.

For interactive work, I would also create a disposable Git branch first:

git switch -c ai/pi-evaluation
pi

Pi can modify files in the working directory and can execute shell commands through bash, so Git remains one of the simplest practical rollback layers when evaluating it. If you want a test session that does not persist, pi --no-session runs in ephemeral mode.

Project instructions belong in AGENTS.md. A useful starting file might look like this:

# Project Instructions

- Read the existing implementation before modifying files.
- Keep changes narrowly scoped to the requested task.
- Run `npm test` after code changes.
- Run `npm run lint` before declaring the task complete.
- Do not modify database migrations unless explicitly requested.
- Do not access production infrastructure.
- Explain any destructive command before running it.

Pi also understands CLAUDE.md while walking project directories, and AGENTS.override.md can override the normal project instructions for a directory.

Then give it a concrete task:

Read the authentication module and its tests.

Find one maintainability problem that can be fixed without changing public behaviour. Explain the proposed change first, then implement it and run the relevant tests.

This is a better agent evaluation than asking it to generate a new toy application. Existing code forces the agent to discover constraints, preserve behaviour, choose relevant files and verify its work.

Why Pi Coding Agent is an editable harness

Pi’s most important architectural idea is that the coding agent itself should remain editable. The extension system uses TypeScript modules that can register tools, subscribe to lifecycle events, intercept tool calls, inject or transform context, add commands and modify the terminal interface. Project-local extensions can also be reloaded with /reload, which makes experimenting with the harness surprisingly immediate.

In simplified form, Pi looks like this:

The diagram is simple because Pi is trying to keep the control plane simple. That gives you an unusual option: when the agent lacks a capability, you do not necessarily have to wait for the Pi maintainers to add it — you can add the behaviour yourself. An extension can create a new model-callable tool, inspect a proposed bash call and block commands matching your own policy, insert dynamic project information before a turn, alter compaction behaviour or expose a custom command inside the terminal UI. That is a much deeper extension surface than changing a system prompt.

MCP integration is not treated as a mandatory built-in part of Pi’s minimal core. It can be added through the same extensibility model, which is consistent with the broader design: specialised integrations live above the small default harness rather than permanently expanding it.

The same harness is also reusable outside the interactive terminal. Pi ships an SDK for embedding the agent session in Node.js applications, and an RPC mode (pi --mode rpc) that speaks JSON over stdin/stdout for non-Node hosts, IDEs and custom UIs.

The four-tool idea is more serious than it looks

I initially thought about coding-agent tools in two groups. The first contains primitives: read a file, modify a file and execute a command. The second contains conveniences: repository search, test runners, issue trackers, browser tools, deployment tools, database helpers, code intelligence and specialised planners. Pi keeps the primitive layer small and allows the convenience layer to remain optional.

There is an architectural advantage to this. A team working on Kubernetes infrastructure can build a very different Pi from a team maintaining a TypeScript monorepo, without both teams carrying the other’s tools in the same default agent. This is where Pi stops looking like a stripped-down Claude Code alternative and starts looking like a framework for building your own coding agent.

The price is maintenance. Once you depend on custom extensions, their behaviour becomes part of your developer platform: you need to review them, version them and occasionally update them as Pi evolves. That is the hidden Pi tax — you gain ownership of the agent, and ownership comes with maintenance.

Skills and packages keep customisation modular

Not every custom behaviour needs to become an extension. Pi supports skills that package instructions, scripts and reference material around a capability. Skills use progressive disclosure: Pi can advertise the available skill to the model while loading the full instructions only when the capability is needed. That is useful for workflows such as deployment reviews, database migrations, release preparation or framework-specific code review; instead of permanently injecting pages of instructions into every conversation, the agent can load specialised guidance on demand. If you already build Claude Skills, the mechanics will feel familiar — see Claude Skills and SKILL.md for developers for the SKILL.md layout and trigger tuning.

Pi Packages go further by bundling extensions, skills, prompt templates and themes. Packages can be installed from npm or Git repositories and can be pinned to specific versions:

pi install npm:@foo/pi-tools@1.2.3
pi list

The package model is powerful, but treat packages more like executable developer tooling than harmless prompt collections. A Pi extension can execute code with the permissions of the Pi process, and a skill can also instruct the model to execute code, so installing an unknown package deserves essentially the same suspicion as installing an unknown development dependency.

Session trees in Pi Coding Agent

Many coding assistants treat a conversation as a mostly linear transcript. Pi stores sessions as a tree, which means you can return to an earlier point, try another approach and retain both paths inside the session rather than destroying one history or creating a pile of unrelated chats.

The main commands are straightforward:

/resume
/tree
/fork
/clone
/compact

/tree lets you navigate within the current session tree. /fork creates a new session from an earlier user message, while /clone duplicates the currently active branch into a separate session. From the command line, pi -c continues the most recent session and pi -r browses past ones.

The distinction became obvious the first time I used Pi on a debugging pass rather than a greenfield prompt. I let it follow a caching-layer hypothesis for a failing integration test, then forked from the message where that theory had been chosen and started a second branch on transaction isolation. The failed investigation stayed available for contrast instead of contaminating the new path or forcing a fresh chat, which is a useful representation of how debugging actually works: multiple plausible explanations often exist at the same time.

Pi persists sessions as JSONL and can automatically compact older context as conversations approach model limits; branches can also be summarised when you move between them. I would rank this above several more visible coding-agent features: good context management usually matters more than another button in the interface.

Context engineering is a first-class capability

Pi also makes it possible to customise what reaches the model. Extensions can inject information before turns, alter history and participate in compaction. The default compaction system summarises older material while retaining recent conversation, but the mechanism can be replaced or customised.

For advanced teams, this opens interesting possibilities. A large monorepo could inject ownership information only for files the agent is currently touching. A backend project could surface schema metadata when database files enter the context. A long-running migration agent could maintain structured state outside the conversation rather than repeatedly asking the model to rediscover it. This is what I consider Pi’s real long-term strength: coding-agent quality is increasingly constrained by context engineering, tool design and orchestration rather than raw model intelligence, and Pi gives developers unusually direct access to those layers.

Pi Coding Agent security: no built-in sandbox

The most important negative point in this review is simple: Pi does not provide a built-in security sandbox. By default, Pi runs with the permissions of the user and process that started it. Its tools can read and modify accessible files and execute shell commands within that operating-system context.

Pi does have project trust, but project trust is not a sandbox. Project trust controls whether project-local Pi settings, extensions, skills, prompts and similar resources are loaded. Once you are working in a project, it does not create a filesystem, network, process or credential boundary around model-directed tool calls. I actually appreciate that the Pi documentation is explicit about this distinction: a weak pseudo-sandbox can be more dangerous than no sandbox because users may trust a boundary that does not really exist. Pi instead expects meaningful isolation to come from containers, virtual machines, micro-VMs or another policy-controlled runtime.

For disposable personal projects, you may decide that Git and normal operating-system permissions are sufficient. For untrusted repositories, unattended agents, workstations containing production credentials or agents processing externally supplied content, I would use stronger isolation. The Pi documentation describes three patterns:

The important boundary is not just the source directory. An agent that can run shell commands may potentially interact with SSH configuration, cloud credentials, package registries, local services, browser state and anything else available to the process. A production-quality setup therefore needs to think about filesystem mounts, environment variables, network access and credentials together. My preferred evaluation pattern is:

Mounting the real repository read/write into a container still allows the agent to modify that repository; containers help only to the extent that their mounts, credentials, capabilities and network access are actually constrained. Gondolin has a related caveat: custom extension tools still run on the host unless they also delegate into the VM.

There is another security surface worth remembering: extensions and packages. A third-party extension is code running inside the agent environment. Review it before installation, pin important dependencies and avoid treating a public package gallery as an implicit security review.

Two practical checks before you run Pi on a machine you care about:

# Confirm the version you actually have
pi --version

# Disable startup network operations (update checks and install telemetry)
export PI_OFFLINE=1
pi

PI_OFFLINE=1 disables all startup network operations, including update checks, package update checks and install/update telemetry. If you want a finer split, PI_SKIP_VERSION_CHECK=1 turns off only the version check, and PI_TELEMETRY=0 disables install/update telemetry while leaving update checks enabled.

This security model is the main reason I would hesitate before giving Pi to a large engineering organisation as an unmanaged default. Pi provides the pieces to build a strong environment, but it intentionally leaves much of that environment to you.

Pi Coding Agent vs Claude Code and OpenCode

Pi makes the most sense when compared by philosophy rather than by feature count. Among terminal agents, OpenHands is the closer sibling: it also runs from the CLI, but it ships sandboxing and a larger built-in workflow rather than asking you to assemble one. Claude Code has increasingly sophisticated built-in permissions, hooks and subagents. OpenCode exposes configurable allow, ask and deny rules plus built-in agent or subagent concepts. Pi starts lower in the stack.

This is why calling Pi a “Claude Code clone” misses the interesting part. If you are happy with Claude Code’s workflow, Pi does not automatically improve it: Claude Code gives you more security and agent orchestration behaviour without requiring you to assemble those pieces yourself. Pi becomes interesting when you want to change the assumptions underneath the product. Maybe you want the same harness across Anthropic, OpenAI and local models. Maybe your organisation has its own sandbox. Maybe you need a tool that injects internal architecture metadata before every turn. Maybe you want compaction to produce structured engineering state instead of a generic conversation summary. That is Pi territory.

OpenCode is arguably closer philosophically because it also offers substantial configuration. Even there, Pi feels more like a kit for constructing the harness itself, while OpenCode exposes more ready-made agent and permission concepts.

There is no universal winner here. For many developers, Claude Code’s opinionated defaults are an advantage. For others, OpenCode may offer a better middle ground. Pi is the option I would investigate when the sentence “I wish my coding agent worked differently” has become more important than “I wish my coding agent had another feature”.

Should you use Pi Coding Agent?

Pi Coding Agent is one of the more technically interesting coding agents because it refuses to hide the harness. The default implementation is deliberately small, but the extension API, skills, packages, provider layer, SDK, RPC mode and session tree give it a much larger effective surface than its four default tools suggest.

I would recommend Pi most strongly to experienced developers who like constructing their own tooling. It is particularly compelling for AI platform work, experimental coding-agent research, specialised engineering workflows and teams that already have secure execution infrastructure. It is also useful for developers who want to compare models without changing their entire coding environment every time. I would be more cautious for beginners and for organisations expecting enterprise-style policy controls immediately after installation.

The missing sandbox changes how Pi should be deployed, especially when an agent is allowed to operate unattended or can encounter untrusted instructions. Treat Pi as a powerful local developer process rather than a security boundary: for untrusted repositories, unattended operation or environments containing valuable credentials, use an operating-system, container, VM or policy-based sandbox and expose only the resources required for the task.

My overall rating is 8.4/10. That is an editorial verdict rather than the average of the table above, and it could easily become higher for the right user. Pi’s greatest weakness and greatest strength are the same thing: it does not finish the agent for you.

Should you switch from Claude Code? Not automatically. Use Claude Code when its built-in permissions, subagents, hooks and workflow fit the way you already work. Evaluate Pi when you want broader ownership of the harness, provider selection, context construction and tool architecture. For advanced developers, I would not even assume the choice has to be exclusive: Claude Code can remain the polished daily driver while Pi becomes the programmable agent laboratory. After enough customisation, that laboratory may turn into the tool you actually prefer.

Licensing and cost

Pi itself is open source and released under the MIT licence. That does not make model inference free: your actual cost depends on the model provider, API usage, supported subscription authentication, local compute and any sandbox infrastructure you choose to run.

References

• Pi Coding Agent repository: https://github.com/earendil-works/pi
• Pi website and installer: https://pi.dev
• npm package: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
• Gondolin micro-VM: https://github.com/earendil-works/gondolin
• NVIDIA OpenShell: https://docs.nvidia.com/openshell/about/overview
• Licence: MIT