Pi coding agent explained: the minimal open-source agent harness developers are switching to

Pi is a program you run in a terminal. You start it inside a project folder, connect it to a model, and tell it what you want done. It can read files, run shell commands and change code, step by step, until the task is finished. In that sense it does the same job as Claude Code or Codex.

The difference is what it chooses not to include. Pi's README describes it as "a minimal, extensible agent harness that you can make your own". A harness is the program around a model: it sends the model your request and the tool definitions, runs the tools the model asks for, and feeds the results back. Pi keeps that core small and lets you build the rest.

Pi works with many model providers, including Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, xAI, OpenRouter and local models through Ollama. You sign in with an API key or a subscription using /login.

Pi runs a simple loop. When you send a message, Pi builds a request from its system prompt, your context files, the conversation so far, the list of tools and the model settings. The model streams back text and tool calls. Pi runs each tool call, records the result, and if more work is needed it starts another turn. When the model stops asking for tools, the run ends.

Every message, tool call and result is saved in a session file in JSONL format, one JSON object per line. Each entry has an id and points to its parent, so the session is a tree, not a list. If you go back to an earlier message and continue from there, Pi adds a new branch to the same file. The model only ever sees the active branch.

When the conversation gets close to the model's limit, Pi compacts it. By default this starts when the context is within 16,384 tokens of the context window. Pi keeps about the last 20,000 tokens as they are and replaces older messages with a summary. The original entries stay in the file, so nothing is deleted.

Read next: The agent loop: how to make an agent that keeps calling tools reliable

MCP, the Model Context Protocol, is a standard way to plug outside tools into an agent. Pi now connects to MCP servers over stdio or streamable HTTP. You add one with a command such as pi mcp add, check it with pi mcp list, and manage it inside a session with /mcp.

Codemode is Pi's answer to a common problem with many tools: every tool result fills up the context. With codemode, the model writes a short JavaScript script that calls other tools, for example several at once, and filters the results. Only the script's output reaches the model. The script runs in a QuickJS sandbox with no file system, network or timers of its own; it can reach the outside only through tools. Its output is capped at 10,000 tokens by default, and longer output is saved to a temporary file.

The v1.0.0 release notes, published on 1 October 2026, say codemode was made leaner, with about 40% fewer prompt tokens.

Read next: MCP: the protocol that connects agents to tools

Pi is a good way to see how simple the core of a coding agent really is. Strip away the product features and what is left is a loop, a handful of tools, a session log and a way to shrink the context when it gets full. If you can explain those four parts, you can explain any coding agent in an interview.

The trade-off is control against safety. A small harness with no approval prompts is fast and easy to bend to your own workflow, but it puts the job of safety on you. Pi's answer, run it in a container or a VM, is the same answer you would give for any process that runs code you did not write.

To try it, the README gives one command: curl -fsSL https://pi.dev/install.sh | sh on macOS and Linux, or the PowerShell installer on Windows. Then run pi in a project folder and use /login to connect a model.

Read next: The AI Engineering course: agents, tools and context, from the ground up