Pi-Harness: an operations desk around a coding agent

A superset, and what that word commits to

Pi-Harness is described as the operational superset of the Pi Coding Agent, and the relationship is stated in a way that is easy to test: Pi Coding Agent is a subset of Pi-Harness, rendered in the README as a mathematical inclusion.

The claim has two halves. Native Pi runs the agent, and the sessions, configuration, tools, Skills and extensions you already have remain compatible with Pi, so you can keep using Pi outside the desktop app. And the capability table shows where the superset part begins: a long column of rows where the Native Pi column says no and the Pi-Harness column says yes.

Those rows are the interesting part, because they are an explicit inventory of what the project considers missing from a bare coding agent. The agent runtime, the agent loop, sessions, context, compaction, steering, follow-up, models, thinking, tools, Skills, extensions, packages, and MCP or Codemode are all listed as yes for native Pi, in several cases with a note that Pi-Harness adds a visual manager, inspection, or selection and policy on top.

Everything below that line is new. Runs, Trace, Replay, Run Compare, Evaluation, Policy, Budget, Checkpoints, Recovery, Diagnostics, Regression, Artifacts, Multi-Agent, Task DAG, Handoff, Review Gates, Worktree isolation and a project architecture map.

Read as a list, that is a description of what happens when you move from an interactive assistant to something you operate. The first group is about the conversation, the second group is about the process around it.

The workspace, the editor and Git

The features section opens with the workspace, and the design decision is that a session and a project are different starting points.

You can start a standalone chat, or open a project and resume a Pi session. Either way you can follow streaming replies, thinking, tool calls, images and changed files, choose the model, the thinking level and the tools, or compact the conversation. There is a Workspace Tools area that gives access to the Harness and the Agents while preserving your conversation and your draft, which is the detail that makes it usable, since an agent that reloads the page mid-task should not lose what you were typing.

The file handling is deliberately lightweight. You browse and search files, preview media and documents, and edit readable text with syntax highlighting, line numbers, find, undo and redo, explicit save, and external-change conflict protection. The word explicit save is doing work there. An editor that autosaves an agent's output while Git is also tracking the file creates a diff nobody asked for, so requiring an explicit save keeps the working tree under your control.

Git is integrated rather than bolted on. Diffs, history, activity graphs, commits, optional AI commit messages, and worktrees. The worktree support appears twice in the README, once here and once in the agent teams section, and it is the mechanism that keeps an agent's changes away from yours while it works.

The project also has a local conversation history section that starts by listing the other agents you can browse, including Claude Code and Codex, with the desktop variants mentioned. So the history is a place to compare what different agents did on the same project.

Providers, Skills and the model picker

The provider and model section is where the desktop app earns its place for people who work with more than one provider.

You configure Pi-compatible providers with presets or custom endpoints, manage credentials, discover models where supported, test connections, and choose your chat model. Image models are supported for text-to-image or image editing, and you can then download the results.

The testing of connections is worth a mention, because it turns a class of confusing failure into a single visible check. A misconfigured endpoint or an expired key otherwise shows up as a failed request inside a conversation, and by then you have lost the thread of what you were doing.

The Skills, extensions, packages and MCP section covers the extensibility surface. You browse built-in and local Skills, edit them, and manage Pi packages and extensions from a Capabilities area. You can type @ in the composer to search for and invoke an installed Skill, and MCP is connected through supported packages.

Optional add-ons can be installed, updated or removed when you choose, and the README names two of them, Superpowers and Odai.

The division of responsibility is consistent throughout. The engine is Pi's, the packages and Skills are Pi's, and the desktop application is the place where you see them, choose between them and apply policy. Tools, Skills and MCP all get the same treatment, a selection and policy layer on top of the native capability, which is the part that turns an agent that can do anything into an agent you are willing to let work unattended.

Runs, Trace and Replay, and the difference between a run and a chat

The Harness section is the operational core, and it starts with a vocabulary that assumes the agent runs unattended.

You can inspect Runs, Trace and Replay, along with timelines and tool activity. You can compare runs, follow forks and retries in a Run Tree, review tokens, cost and duration, and browse artifacts and project statistics.

The Run Tree is the idea that makes the rest work. When an agent retries, forks or branches, a linear log stops making sense, because there is no longer a single history. A tree structure records that a run was attempted, failed, was retried, and took a different path, and that is exactly the information you need when you come back to a project the next morning and see three conversations and no idea which one produced the file you are looking at.

Replay is the other one. If a run can be replayed, then a failure is reproducible, and reproducibility is what turns debugging an agent from guesswork into a procedure. Combined with the token, cost and duration figures, you can also see that a change in prompt or model made a run more expensive, which is a fact that matters once the bill arrives.

Alongside that, the control side: you set tool policies and per-run budgets, create checkpoints, and resume, fork or retry work. Evaluation, Diagnostics and regression baselines help you check results and investigate failures using recorded run evidence.

The budgets are the part with teeth. A per-run budget is a hard stop on what a runaway agent can spend, and tool policy is a hard stop on what it can do. Neither of those is part of a chat interface.

Agent teams, task dependencies and review gates

The agent teams section describes a scheduler rather than a chat room.

You coordinate Pi agents with reusable teams and templates. Tasks are assigned with dependencies and priorities, and they can be scheduled manually, sequentially or in parallel. Results and artifacts are passed to the next task, and review gates sit between them. Worktrees keep agent changes separate, and budgets, conflict hints, and pause, resume, abort, retry, skip and reassign controls help you manage the work.

The task DAG is the core abstraction here, and the Row for it in the capability table is a hint that the tasks form a directed acyclic graph rather than a list. A graph is what you need when the constraint is a real dependency, such as a schema change that has to land before the code that uses it, and it is also what makes a cycle detectable. A list of tasks with a priority column cannot express that, and a cycle in a list is a deadlock you find out about by watching nothing happen.

The review gates are the other notable piece. A gate between two tasks means a human, or a policy, decides whether the first task's output is acceptable before the second one consumes it. That is a different model from a single agent doing everything, and it is the model that survives contact with work where a wrong answer is expensive.

The conflict hints are a small sign of how the implementation deals with the practical reality of several agents editing one repository, where the worktree separation prevents file collisions but the intent can still conflict. The reassign control is the escape hatch when a task is picked by the wrong agent or the wrong model.

So the local conversation history rounds the picture: the app is where you watch what the agents did, not only where you type at them.

How it is built, and the licensing constraint

The build configuration tells you what this is technically.

It is an Electron application with a Vue 3 interface, built with electron-vite, packaged by electron-builder, and the package scripts show separate build targets for macOS, Windows and Linux, with the macOS target taking an --arm64 or --x64 flag, a combined build for both, and a build:mac:intel for the Intel path. The manifest declares Node 22.22.2 or newer and pins pnpm 9.12.1 as the package manager. The main entry is ./out/main/index.js and the package is marked type module, so the whole thing is ESM.

There is a second electron-builder configuration file with a nomascot suffix and matching dev and compile variants, which suggests a build without the branding elements, presumably for distributions where the trademark is a problem.

The compile step is worth reading, because it shows the build checking itself. The compile script runs a builtin skills check, then a script that verifies the SDK, and only then runs the electron-vite build. So a build fails if the built-in Skills are wrong or the runtime SDK does not verify, rather than producing an application that misbehaves later.

The repository layout is consistent with a project of this size: src/, e2e/ with a playwright.config.ts, tests with vitest.config.ts, benchmarks/, fixtures/, patches/, scripts/, docs/, resources/, and separate tsconfig files for the node and web sides. There is a .pi/ directory, and the .env.example documents the environment variables, including PI_HARNESS_MOCK to force mock mode during development using a fixture Pi environment, PI_HARNESS_PI_CLI_PATH to override the Pi CLI path used for detection, and PI_HARNESS_PI_CONFIG_DIR for a custom Pi config directory.

The licence is AGPL-3.0-only, and the repository carries a NOTICE file and a THIRD_PARTY_NOTICES.md alongside it, which is the arrangement you would expect for a project that bundles a third party agent runtime. The release history is fast, v2.2.1 on 2026-10-18 and v2.2.0 the day before, and the last push was on 2026-10-20.

Editorial conclusion

Adopt Pi-Harness if you are running coding agents as a long-lived process, because the run history, checkpoints, budget controls and recovery are the parts that matter once a session outlives one terminal, and the project keeps your Pi sessions and configuration compatible rather than forking them. Do not adopt it if you want a lighter editor for one agent conversation, since the Electron shell and the operational surface are the cost. Before you build it, read the AGPL-3.0-only terms and the THIRD_PARTY_NOTICES.md file, check the Node requirement of 22.22.2 or newer with pnpm 9.12.1, and keep secrets out of VITE_ prefixed variables, because those values are bundled into the renderer.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. wangmiaozero/pi-harness on GitHub