Pi harness, defined: the open-source loop around the model

What a harness is

A harness is the loop that turns a model into an agent. It builds a request from the system prompt and the conversation, sends it to the model, reads the tool calls that come back, runs them and records the results. Pi describes itself in one sentence: Pi is a minimal agent harness.

Model, harness, framework and runtime get used as if they were one thing. They are four layers, and each answers a different question.

• Model. The network that predicts tokens. It cannot read a file or run a command. It can ask for one.
• Harness. The loop and the tool surface that turn those requests into actions, plus the transcript it writes.
• Framework. A library you import to write that loop yourself, with your own tools, retries and state.
• Runtime. The machine a session runs on, the rules on which tools may run there, and what happens to the work at the end.

Kortix's docs use the word runtime for the harness itself: "A harness is the agent runtime inside a session's sandbox. It runs the model loop, calls tools and writes the transcript." That sentence stops at the sandbox wall. Everything outside it, from the machine image to the person who merges the branch, is the runtime a team actually manages. The model and the harness decide what a session can do. The runtime decides whether a team can leave it running.

What Pi's harness actually does

The loop is short enough to describe in a paragraph. A message lands on the active branch, Pi builds a request from the system prompt, that branch, the available tools and the model settings, and the provider streams back text and tool calls. Pi records the response, runs each tool call and records the result. A turn ends there, and another starts only if the results or the queue ask for one.

Four tools, four modes

Pi enables four built-in tools by default: read, bash, edit and write. Almost everything else a coding agent does, from running a test suite to calling an internal API, arrives through bash or through an extension someone installed. Pi runs in four modes: interactive, print/JSON, RPC and SDK. Print mode is pi -p "query", JSON mode writes agent events as JSONL, RPC speaks JSONL over stdin and stdout, and the SDK creates sessions in process. That reach is why Pi turns up inside other tools as well as in a terminal.

Providers and context

Pi reads provider keys from the environment and documents Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, xAI, Hugging Face and Ollama, among others; /model switches mid-session. On the context side, AGENTS.md loads at startup from ~/.pi/agent/, from parent directories and from the current directory, and SYSTEM.md replaces or appends to the system prompt. Compaction summarizes older messages as the window fills.

Sessions are stored as trees in a single file, so /tree returns to any earlier point and the path you take from there is another branch of the same session. /export writes HTML and /share uploads a gist. A team reading a transcript later can see where a wrong turn began, then take the earlier branch instead.

What a minimal harness hands back to you

The README states the default in two sentences. Pi's usage docs put the practical consequence plainly: "Pi does not ask before every tool call." On a laptop that is a fair bargain. The person at the keyboard sees each call, can stop it and reads the diff before it goes anywhere.

The calculation changes on a shared machine, in CI or on a schedule, where the same default hands the model everything the process can reach. Pi's answer is to keep the core small: it ships powerful defaults and skips features like sub-agents and plan mode, and its docs list those, plus permission gates, path protection and sandboxing, as things to build or install. Pi's package catalogue has an extension for most of them. That approach works, and it moves the work of supervision onto whoever runs it. An extension runs inside the Pi process with the same operating-system permissions, so the boundary after installing one sits where it sat before. Pi coding agent extensions covers what that costs and how to choose.

The half a harness does not ship

A Kortix session puts the harness on a machine the platform owns, and the thing a team manages is the session. Every new session runs Pi, and runtime: in kortix.yaml selects nothing, so there is no harness to pick there. What gets configured is the session around the loop: a branch cut from base_ref and named with the session_id, permission rules that resolve each tool to allow, ask or deny before it runs, and a change request that a person reviews and merges. The steps are in Kortix's session docs.

Kortix's own capability table reads as a boundary document. A Pi session serves subagents through the task tool, conversation compaction, project slash commands, steering mid-turn and the v2 session log. Rewind, fork, a harness-side MCP connection, a todo list, a shell turn and attaching the harness's own terminal client are listed as not served, and a request for one answers 501 with code: "feature_not_supported". A request for the runtime config document answers 404. Pi also has a tool of its own, codemode, where the model writes a script that calls the other tools and only the script's output returns to it. The pi-only directory, harnesses/pi/, holds settings.json, extensions/, skills/ and prompts/, so what the harness loads can live in the repo with everything else.

Those fields, and the table that names what a Pi session serves, are documented in Kortix's docs.

When Pi on its own is the right answer

Pi on a laptop is a good tool for one developer with their own repository and their own provider keys. The loop, the four tools and a session tree are enough for that setup, and the person at the keyboard is the runtime: they watch each call, read the diff and answer for the result.

The calculation changes with a second person, with a session that should outlive the laptop, or with a rule that has to hold when nobody is watching. Those are the cases running Pi in the cloud covers, and the Pi coding agent guide covers the install and the first session in a terminal.