pi-harness README

The project's README from github.com/wangmiaozero/pi-harness. As one markdown file: README.md.

Pi-Harness

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Русский · Français · Deutsch

Pi-Harness

The Operational Superset of Pi Coding Agent

Native Pi with a visual workspace, run controls, recovery, and agent teams.

Pi Coding Agent ⊂ Pi-Harness

Download · Create a custom skin · Screenshots

Releases macOS, Windows, Linux AGPL-3.0-only GitHub Stars

Why Pi-Harness?

Pi-Harness brings Pi Coding Agent into a desktop workspace for macOS, Windows, and Linux. Manage conversations, projects, files, Git, models, and Skills in one place, with tools to inspect runs, control budgets, recover work, and coordinate agent teams.

Native Pi runs the agent. Your Pi sessions, configuration, tools, Skills, and extensions remain compatible with Pi, and you can continue using Pi outside the desktop app.

Pi vs Pi-Harness

Pi-Harness is the operational superset of Pi Coding Agent: native Pi capabilities form the foundation, with observation, control, recovery, orchestration, and a visual workspace added around them.

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

Features

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.

Providers and models

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.

Skills, extensions, packages, and MCP

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. Connect MCP through supported packages. Optional add-ons such as Superpowers and Odai can be installed, updated, or removed when you choose.

Harness: observe, control, and recover

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.

Agent teams and task 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.

Local 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

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 conversation history keeps source sessions read-only, and continuing a task starts a new Pi conversation.

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.

Themes and custom 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.

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.

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.

Screenshots

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

Classic theme

Workspace

Workspace

Git · Providers and models · Capabilities · Harness · Project architecture

Git

Git

Providers and models

Providers and models

Capabilities

Capabilities

Harness

Harness

Project architecture

Project architecture

Ming interfaces

General settings · Theme and skin gallery

General settings

General settings

Theme and skin gallery

Ming · Snowbound official · Ming · Snow flute scholar · Ming · Moon scholar · Starship Cockpit · macOS 27 · Liquid Ether

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

Download

Download a published installer from GitHub Releases and choose the file for your platform.

Platform Installer
macOS Apple Silicon .dmg · arm64
macOS Intel .dmg · x64
Windows x64 .exe · Windows installer
Linux x64 .AppImage

Packaged users do not need to clone the repository or install pnpm. Follow the environment requirements in the release notes for the installer you download.

macOS community builds may be unsigned. If the first launch is blocked, use System Settings → Privacy & Security → Open Anyway.

Get started

  1. Launch Pi-Harness and check the environment in Overview.
  2. Configure a provider, test the connection, and select a model.
  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 for Harness controls or agent teams.

Requirements

The desktop app supports macOS Apple Silicon, macOS Intel, Windows x64, and Linux x64. Pi Coding Agent can be installed or repaired from the app where supported. Source development and packaging require Node.js ≥ 22.22.2 and pnpm 9.12.1. These build requirements are separate from the requirements of a published desktop installer.

Documentation

Credits

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

Created and maintained by wangmiao · [email protected].

License

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

Copyright © 2026 wangmiao.

pi-harness (wangmiaozero/pi-harness)

Searching Database…

1K ·GitHub
Pi-harness
What is this?Pi-Harness is a desktop operational superset of Pi Coding Agent: it adds a visual workspace, observability, governance, recovery, evaluation, and multi-agent orchestration on top of native Pi, while staying fully compatible with Pi sessions and Skills.
Is this a standalone app or a plugin for Pi?It's a standalone Electron/Vue3 desktop app for macOS, Windows, and Linux that wraps and extends the native Pi Coding Agent runtime with a GUI, rather than a code library or in-editor plugin.
How do I get it running?Download the published installer for your OS from GitHub Releases — a .dmg for macOS (arm64 or x64), a .exe for Windows x64, or an .AppImage for Linux x64 — then launch it and check the environment in Overview.
Do I need Pi Coding Agent installed separately first?You need native Pi Coding Agent, but Pi-Harness can install or repair it for you from inside the app; building from source instead requires Node.js ≥ 22.22.2 and pnpm 9.12.1.
Any install pitfalls I should know about?Unsigned macOS community builds can be blocked on first launch, requiring you to allow them via System Settings → Privacy & Security → Open Anyway; the architecture map also only gives full dependency analysis for JavaScript, TypeScript, and Vue, with other languages getting just a file-level index.
Which systems does it actually run on?It supports macOS Apple Silicon, macOS Intel, Windows x64, and Linux x64.
Does browsing my past agent conversations cost model tokens?No — browsing local conversation history, previews, and project architecture analysis all run locally with no model tokens; AI summaries or descriptions are optional and only run when you explicitly request them.
What does Pi-Harness add on top of native Pi Coding Agent?It layers run inspection (Trace, Replay, Run Compare), tool policies, per-run budgets, checkpoints, evaluation, diagnostics, and multi-agent task orchestration with worktree isolation on top of everything native Pi already does.
Can it import my history from other coding agents?Yes, it can browse and search local Claude Code, Codex, Cursor, Cursor Agent, Gemini CLI, and OpenCode conversation history alongside Pi's own, and let you continue a past conversation as a new Pi chat.
Can I customize how it looks?Yes, it ships with classic, Ming, Starship Cockpit, and macOS 27 themes, plus support for importing a custom skin built from the Pi-Harness Custom Skin Starter template.
How does multi-agent task orchestration work?You coordinate reusable agent teams and templates, assign tasks with dependencies and priorities, run them manually, sequentially, or in parallel, and manage them with review gates, worktree isolation, and pause/resume/retry controls.
What are similar projects?foreman, PI-Desktop, codex-host, bivor, ruflo, pi-pocket, evenfire, oh-my-opencode-slim
Which topics is it in?agent-observability, pi-agent, pi, pi-coding-agent, vue3, agent-harness, agplv3, agent-framework, orchestration, agent-orchestration, apple-silicon, electron
Creator
wangmiaozero
Size
194.4 MB
Stars
1K
Updated
CommitOct 18Releasev2.2.0Oct 17
Age
1mo
Commits · 90 Days