pi-harness

Pi-Harness

Pi-Harness is the desktop workspace and operational control plane around Pi Coding Agent. Pi is the native execution engine; Pi-Harness adds visual operations, governance, recovery, evaluation, and multi-agent orchestration. Your Pi sessions, configuration, tools, Skills, and extensions remain compatible, and you can continue using Pi outside the app.

macOS · Windows · Linux. Community installers bundle Pi and Node.js — no separate runtime installation needed. Get started →

Product Preview

Real screenshots from this repository. Click an image to view it at full size.

Workspace

Keep conversations, project files, and Git close to the work.

[Workspace — conversations and project files]

Harness

Inspect session status and queued instructions in the Harness console.

[Harness — session status and queued instructions]

Multi-Agent

Open Workspace → Tools → Agents to coordinate teams, task dependencies, handoffs, review gates, and isolated worktrees. Explore multi-agent orchestration →

A sample team configured in the desktop app, before execution: three agents are idle and all tasks are pending.

[Multi-Agent — configured team before execution]

[Multi-Agent — pending tasks with dependencies and a review requirement]

More interfaces and themes → · Complete screenshot index

Why Pi-Harness

Observe — understand each run

Inspect Runs, Trace, Replay, and Evaluation to see tool activity, compare outcomes, and investigate failures from recorded evidence.

Control — keep work recoverable

Use Policy, Budget, Checkpoints, and Recovery to set tool permissions and spending limits, preserve recovery points, and resume, fork, or retry work.

Orchestrate — coordinate a team

Use Agent Teams, Task DAG, and Worktrees to assign dependent tasks, pass results between Pi agents, and keep their changes separate.

Key Features

Native Pi Runtime

Pi Coding Agent runs the agent loop, sessions, context, compaction, steering, follow-up, tools, models, and thinking. Pi-Harness provides visual management around those native capabilities.

Capability	Native Pi	Pi-Harness
Agent Runtime	Yes	Native Pi
Agent Loop	Yes	Native Pi
Sessions	Yes	Yes + visual management
Context	Yes	Yes + inspection
Compaction	Yes	Yes + visual control
Steering	Yes	Yes
Follow-up	Yes	Yes
Models	Yes	Yes + manager
Thinking	Yes	Yes + visual control
Tools	Yes	Yes + selection and policy
Skills	Yes	Yes + manager
Extensions	Yes	Yes + manager
Packages	Yes	Yes + manager
MCP / Codemode	Yes	Yes + selection and policy
Runs	—	Yes
Trace	—	Yes
Replay	—	Yes
Run Compare	—	Yes
Evaluation	—	Yes
Policy	—	Yes
Budget	—	Yes
Checkpoints	—	Yes
Recovery	—	Yes
Diagnostics	—	Yes
Regression	—	Yes
Artifacts	—	Yes
Multi-Agent	—	Yes
Task DAG	—	Yes
Handoff	—	Yes
Review Gates	—	Yes
Worktree isolation	—	Yes
Project architecture map	—	Yes

Agent Harness Control Plane

Inspect Runs, Trace, Replay, timelines, and tool activity. Compare runs, follow forks and retries in the Run Tree, review tokens, cost, and duration, and browse artifacts and project statistics.

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.

Multi-Agent Orchestration

Coordinate Pi agents with reusable teams and templates. Assign tasks with dependencies and priorities, schedule them manually, sequentially, or in parallel, pass results and artifacts to the next task, and use review gates. Worktrees keep agent changes separate; budgets, conflict hints, and pause, resume, abort, retry, skip, and reassign controls help you manage the work.

Universal Conversation History

Browse Claude Code, Codex (including desktop and archived conversations), Cursor, Cursor Agent, Gemini CLI, OpenCode, and Pi history together. Search, filter by source, project, or date range, and add custom history folders.

View the original conversation in read-only mode, preview a handoff, and edit the next instruction before continuing in a new Pi chat under the same project. Browsing, local previews, and scan retries use no model tokens. Optional AI summaries use your configured model only when requested.

Project Architecture Visualization

Open Architecture in Workspace to explore modules, dependencies, entrypoints, and source references. Filter by package, focus on a module, browse map pages, zoom, or use fullscreen. Save analysis snapshots, see when source changes make them stale, and export JSON, offline HTML, or the current view as PNG.

Maps describe supported static dependencies; they do not establish a complete function-call graph.

Local analysis uses no model tokens; AI descriptions are optional. JavaScript, TypeScript, and Vue import relationships are analyzed locally, while other supported languages have a file-level index. The analysis shows its coverage and limitations.

Providers / Models / Skills / MCP

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

Configure OpenCode Zen / Go from the OpenCode tab under Models: save your API key and enable the models you want in the workspace. Models load automatically and can be verified individually or together. Access and charges depend on your official account and selected model; paid verification requires your permission. See OpenCode's official model information for pricing and data policies.

Browse built-in and local Skills, edit them, and manage Pi packages and extensions from Capabilities. Type @ in the composer to search and invoke an installed Skill. Manage MCP servers in Settings → MCP. Optional add-ons such as Superpowers and Odai can be installed, updated, or removed when you choose.

Desktop Companion

Enable the optional BigFish companion in Settings → Desktop Pet to see thinking, tool activity, waiting, and completion feedback on your desktop. It is off by default and remains available when the main window is minimized.

While idle, choose from 101 actions in a searchable right-click menu. During tasks, manual interactions pause while dragging keeps the task animation intact. Import local pet packs and adjust size, opacity, and bubble settings with sliders.

[Desktop pet settings and sliders]

Agent Settings

Available in v2.2.10 and later. The seven settings pages are: AI, Realtime voice, Shortcuts, Instructions, MCP, Subagents, and Remote hosts. Check the release notes for availability in downloaded installers.

Set default thinking, automatic compaction, retry behavior, and workspace preferences in Settings → AI. Record your own shortcuts for the command palette, settings, new sessions, and closing tabs, or restore their defaults. Edit global or project instructions in Settings → Instructions.

Create reusable subagents with a role, instructions, model, thinking level, and tools in Settings → Subagents. Choose a shared workspace or an isolated worktree, then start a task or reuse the template in a team.

Realtime Voice

Configure OpenAI Realtime, Gemini Live, or Codex Live in Settings → Realtime voice, then open the waveform button beside the workspace composer. Use a supported provider account or a separate API key; Codex Live uses your existing Codex sign-in in Pi. Service availability and charges depend on your account.

Review the target conversation before starting a call. Sharing recent context is off by default; when enabled, it includes only the last six plain-text messages, excluding attachments and tool results. During a call, mute or end it and view transcripts from the floating controls, including when navigating to another page. Review voice work requests before sending them to the work conversation.

MCP Servers and Marketplace

Open Settings → MCP to add local-command or HTTP servers, search and filter All / Global / Project, choose a project, and edit or enable each server in its own scope. Scan configurations from other tools and review them before importing.

The marketplace includes 15 built-in server templates, including Memory, Context7, Playwright, Filesystem, and GitHub, plus search and pagination for the official MCP registry. Preview the configuration and destination before saving. Templates are available to install; they are not all enabled by default. Imported and official-registry entries are saved disabled for you to configure before enabling.

Remote Hosts

Pair a host running pi-host from Settings → Remote hosts using its address and pairing token. Connect or disconnect hosts, browse their projects and sessions, view conversations, send prompts, and respond to approval requests. The remote host must already be running and reachable.

Custom Themes and Skins

Choose classic palettes, Ming themes, Starship Cockpit, macOS 27 backgrounds, or an imported custom skin. New installations start in Dark. Customize chat display names, app icons, local background images, window and screen glow, and the input flame effect. Startup animation accompanies the environment check; mascot-free builds retain the general appearance controls.

Create your own skin

Use the Pi-Harness Custom Skin Starter to create the visual style you want.

1. Use the starter repository as a template or download it.
2. Open it with your coding agent and describe your preferred style using the included prompt.
3. Import the completed project from Settings → Theme → Import Skin.

The multilingual starter includes guidance for colors, previews, wallpapers, and optional character artwork. Keep your skin in its own repository to update and share it independently.

Workspace, files, and Git

Start a standalone chat or open a project and resume a Pi session. Follow streaming replies, thinking, tool calls, images, and changed files; choose the model, thinking level, and tools, or compact the conversation. Workspace Tools gives you access to Harness and Agents while preserving your conversation and draft.

Browse and search files, preview media and documents, and edit readable text with syntax highlighting, line numbers, find, undo/redo, explicit save, and external-change conflict protection. The lightweight editor keeps file editing focused. Git provides diffs, history, activity graphs, commits, optional AI commit messages, and worktrees.

Environment and app settings

Check Node.js, npm, PATH, Pi Coding Agent, and the active configuration. Install, update, or repair Pi where supported, inspect environment diagnostics, manage configuration backups, and check for app updates. The interface is available in eight languages.

Harness Plugins — Extend the Control Plane

Plugin SDK v1.0.0 · Included starting with Pi-Harness v2.2.6.

Extension	Purpose
Pi Extensions	Extend the Pi agent itself.
Skills	Give the agent instructions and workflow knowledge.
MCP	Connect the agent to tools and external services.
Harness Plugins	Extend Pi-Harness operations around the agent.

Contribute Harness Event Subscribers, Custom Evaluators, Trace Exporters, and Agent Team Templates. Evaluations are supplementary, exports use authorized JSON data, and team templates create pending workflows for you to inspect and start.

Try the maintained SDK examples: Run Metrics, Quality Evaluator, and Team Template.

In a source build, open Workspace → Tools → Harness → Harness Plugins → Install local plugin, choose its folder, review permissions and enable it. Installation executes no code. Executable plugins require explicit native trust approval: the separate process is not a security sandbox; approved Node code can access your computer. Use declarative templates for untrusted content.

Develop and install · Architecture · SDK API · Security boundary

Architecture

Pi-Harness surrounds the native Pi runtime with a workspace and operational controls. Agent teams use the same Pi execution engine; the diagram shows module relationships, not class inheritance.

flowchart TD
    subgraph Desktop["Pi-Harness Desktop"]
        W["Visual Workspace"] --> H["Harness Control Plane"]
        A["Agent Teams / Task DAG"] --> H
        W --> G["Files / Git / Worktrees"]
        A --> G
        C["Providers / Models / Skills / MCP"]
    end
    H --> P["Native Pi Coding Agent"]
    C --> P
    P --> M["Model Providers"]

Pi owns execution and native sessions. Harness observes runs and applies policies, budgets, checkpoints, recovery, and evaluation around that execution. Conversation history and project architecture analysis are workspace tools; themes customize the visual experience.

Quick Start

Download from GitHub Releases →

Community installers include Pi, Node.js, npm, and npx. You do not need to install Pi or Node.js beforehand, clone this repository, or install pnpm to use the app. Choose the standard package or nomascot without mascot artwork. Follow the notes for the version you download; older packages may have different requirements.

macOS

Choose the .dmg for Apple Silicon (arm64) or Intel (x64), open it, and drag Pi-Harness to Applications.

Windows

Download the x64 .exe installer, run it, and choose an installation directory.

Linux

Download the x64 .AppImage, grant it executable permission, and open it:

chmod +x "./Pi-Harness-VERSION.AppImage"
./Pi-Harness-VERSION.AppImage

Replace VERSION with the downloaded version. Linux native validation targets Ubuntu 24.04; other distributions and FUSE/desktop integration need their own checks. Windows/Linux ARM64 remain preview targets; check the release notes for availability and validation results.

Community Release signing and verification

Community releases are free. macOS packages use ad-hoc signing without Apple Developer ID or notarization. Windows installers are unsigned and may show SmartScreen warnings. Verify the official download source and checksum before allowing the app to open. If macOS blocks first launch, use System Settings → Privacy & Security → Open Anyway for that app. Keep system security protections enabled.

Download SHA256SUMS alongside the installer. Calculate its hash and compare it with the same filename in the list (replace VERSION and the architecture with your download's values):

# macOS
shasum -a 256 "Pi-Harness-VERSION-arm64.dmg"
# Linux
sha256sum "Pi-Harness-VERSION.AppImage"

# Windows
Get-FileHash ".\Pi-Harness-Setup-VERSION.exe" -Algorithm SHA256

SHA256 checks consistency with the checksum list; it does not independently prove publisher identity. Use the official GitHub Releases page. Report suspected vulnerabilities privately to tuziling84@gmail.com.

Community builds check for new versions in the app and open the official Releases page for manual download and installation on all platforms. Automatic installation remains disabled until cross-version installation is verified. Existing installations keep their previous update behavior. See Community Release and update details.

Your first Pi session

1. Launch Pi-Harness and check the environment in Overview.
2. Configure a provider, test the connection, and select a model. Model access may require credentials and incur provider charges.
3. Start a standalone chat or open a project.
4. Start or resume a Pi session, then work with conversations, files, and Git.
5. Open Workspace → Tools → Harness / Agents to inspect runs or coordinate a team.

Start a voice conversation

To start a realtime voice conversation:

1. Open Settings → Realtime voice, enable voice, choose the service and account, and save.
2. Return to a workspace conversation and click the waveform button beside the composer.
3. Review the conversation and optional context sharing, then select Start realtime voice and allow microphone access.
4. Use the call controls to mute, view details, or end the call. Confirm any work request before sending it to the coding agent.

Requirements

Community release validation covers macOS Apple Silicon, macOS Intel, Windows x64, and Linux x64; platform availability is subject to each release's verified results. The bundled Pi and Node runtimes are ready to use, with System and Custom runtime choices available in settings. Source development and packaging require Node.js 24 LTS (≥ 24.22.1) and pnpm 9.12.1; installed users do not need these build tools.

Screenshots

Product screenshots are grouped by theme. Browse the complete screenshot index for additional views.

Desktop Companion

[Context menu]

[Searchable action list]

Conversation history

[Conversation history]

Session cleanup

[Session cleanup]

Classic theme

Lightweight file editing

[Lightweight file editing]

Workspace voice

Setup and preparation before a call:

[Workspace voice preparation]

MCP marketplace

[MCP marketplace and built-in server templates]

Settings page	Screenshot
AI preferences	View
Realtime voice	View
Keyboard shortcuts	View
Global and project instructions	View
MCP servers	View
Subagents	View
Remote host pairing	View

Git

[Git]

Providers and models

[Providers and models]

Capabilities

[Capabilities]

Harness

[Harness]

Project architecture

[Project architecture]

Ming interfaces

General settings

[General settings]

Theme and skin gallery

[Theme and skin gallery]

Theme gallery

Ming · Snowbound official

[Ming · Snowbound official]

Ming · Snow flute scholar

[Ming · Snow flute scholar]

Ming · Moon scholar

[Ming · Moon scholar]

Starship Cockpit

[Starship Cockpit]

macOS 27 · Liquid Ether

[macOS 27 · Liquid Ether]

Developers & Community

Local development

Install Node.js 24 LTS (≥ 24.22.1) and pnpm 9.12.1, then run:

git clone https://github.com/wangmiaozero/pi-harness.git
cd pi-harness
pnpm install --frozen-lockfile
pnpm dev

For development without a separate Pi installation, use the sample configuration in fixtures. In Settings, point the manual configuration directory at the absolute path to fixtures/mock-pi. Sample configuration does not provide live model access; configure your own provider when needed.

Checks

pnpm typecheck
pnpm lint
pnpm test
pnpm compile

For changes to key desktop flows, also run pnpm test:e2e.

Participate

• Report a bug or suggest an improvement. Include your app version, operating system, and steps to reproduce; remove credentials and private conversation content.
• Open a pull request with the problem, user-visible change, and validation results. Documentation, translations, themes, and focused fixes are welcome.
• Create and share a custom skin.
• Community QQ group: pi-harness · 1109717308.

Documentation

• Agent settings guide
• Screenshot index · Changelog
• Community Release · Troubleshooting
• English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Русский · Français · Deutsch

Credits

Pi-Harness is built around the official Pi Coding Agent and Pi Agent Harness.

Created and maintained by wangmiao · tuziling84@gmail.com.

PR contributors

We welcome pull requests that improve Pi-Harness. Thank you to every contributor for helping make the project better!

License

Pi-Harness is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).

Copyright © 2026 wangmiao.