pi-harness
Observe, control, and orchestrate native Pi agents in one desktop workspace.
Automatically checked · GitHub checked 2026-11-15
Overview
The Operational Superset of Pi Coding Agent
Observe, control, and orchestrate native Pi agents in one desktop workspace.
Pi still runs every agent. Pi-Harness adds the workspace, run history, recovery and agent teams around it,
and your Pi sessions, configuration, Skills and extensions keep working inside and outside the app.
Pi Coding Agent ⊂ Pi-Harness
Download · Watch · Features · Harness Plugins · Docs · Changelog
English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Русский · Français · Deutsch
赞助商
|
Pi-Harness × Infistar.cc | Claude, GPT, Gemini, Grok, DeepSeek & more, one key, a fraction of official prices 💥 Up to 99% off: from 0.1x official pricing ✅ Official upstreams, 100% genuine models: no downgrades, no dilution, every model verifiable ⚡ 1,000+ redundant routes with automatic failover: one route stumbles, the next takes over 🧩 200+ models from 16 brands: text, image and video with one key 🏆 Recommended by 100+ top open-source projects, the largest with 100k+ stars 🎯 Run Pi-Harness coding agents across Claude, GPT and Gemini with one key, at a fraction of official prices 🎁 Pi-Harness users: sign up through the exclusive link and get CNY 5 free https://infistar.cc/register?aff=S26RFM4B&ref_source=link |
|
Pi-Harness × TokenArmy Claude Pro 日租 · 独享账号,低至 $1.34/天,不封号 Claude API 按量计费 · 低至官方价格 1.25 折,失败不扣费 Pi-Harness 用户专属注册链接 价格与服务以 TokenArmy 平台规则为准。 |
|
【腾讯云】WorkBuddy 全场景 AI 办公工作台,团队旗舰版低至198元/月 https://cloud.tencent.com/act/cps/redirect?redirect=6871&cps_key=ece2099a1da90c2f7a4a4c437ad623f8&from=console |
Is Pi-Harness for you?
Pi Coding Agent works well in a terminal. On real projects you soon want more: to see what each run actually did, to get back to a good state when a run goes wrong, and to split a bigger job across several agents. Pi-Harness puts all of that in one desktop app, on top of the same Pi:
- See every run: Runs, Trace, Replay and Evaluation show tool activity, compare outcomes, and let you investigate failures from recorded evidence.
- Keep work recoverable: Policy, Budget, Checkpoints and Recovery set tool permissions and spending limits, keep recovery points, and let you resume, fork or retry.
- Coordinate a team: Agent Teams, Task DAG and Worktrees assign dependent tasks, pass results between Pi agents, and keep each agent's changes separate.
- Stay on native Pi: Pi runs the agent loop, sessions, context, tools, models and thinking. Pi-Harness manages them visually, and you can keep using Pi outside the app.
It's for you if you use Pi on real projects and want to see, steer and coordinate its work from one window. If one chat in a terminal is all you need, Pi on its own is enough.
Runs on macOS, Windows and Linux. Community installers bundle Pi and Node.js, so there is nothing else to install first.
Watch
Work mode. DeepSeek opens into the coding workspace. 13 seconds.
Welcome back. The companion appears and the workspace overview opens. 11 seconds.
Quick start
1 · Install. Download the installer for your system from GitHub Releases:
| macOS | The .dmg for Apple Silicon (arm64) or Intel (x64). Open it and drag Pi-Harness to Applications |
| Windows | The x64 .exe installer. Run it and choose an installation directory |
| Linux | The x64 .AppImage. Make it executable, then open it |
chmod +x "./Pi-Harness-VERSION.AppImage" # replace VERSION with the downloaded version
./Pi-Harness-VERSION.AppImage
Installers include Pi, Node.js, npm and npx: you don't need to install Pi or Node.js, clone this repository or install pnpm. Release validation covers macOS Apple Silicon, macOS Intel, Windows x64 and Linux x64, and each release's verified results decide which platforms it ships for. Linux validation targets Ubuntu 24.04; other distributions and FUSE or desktop integration need their own checks. Windows and Linux ARM64 are preview targets. Older packages may have different requirements, so follow the notes for the version you download. macOS builds are ad-hoc signed and Windows installers are unsigned: see Verify your download.
2 · Check the environment. Launch Pi-Harness and check the environment in Overview.
3 · Choose a model. Open Free Models in the chat model picker to try Kilo. To use your ChatGPT subscription, open Models → New provider → ChatGPT and sign in through your browser. You can also configure a provider with an API key.
4 · Start working. Start a standalone chat or open a project, then start or resume a Pi session and work with conversations, files and Git in one window. Open Workspace → Tools → Harness / Agents to inspect runs or coordinate a team.
Verify your download
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 the first launch, use System Settings → Privacy & Security → Open Anyway for that app. Keep system security protections enabled.
Download SHA256SUMS alongside the installer, calculate the hash of your file and compare it with the same filename in the list (replace VERSION and the architecture with your download's values):
shasum -a 256 "Pi-Harness-VERSION-arm64.dmg" # macOS
sha256sum "Pi-Harness-VERSION.AppImage" # Linux
Get-FileHash ".\Pi-Harness-Setup-VERSION.exe" -Algorithm SHA256 # Windows
SHA256 checks consistency with the checksum list; it does not independently prove publisher identity. Use the official GitHub Releases page, and report suspected vulnerabilities privately to [email protected]. Community builds check for new versions in the app and open the Releases page for manual download and installation on all platforms. Automatic installation stays disabled until cross-version installation is verified, and existing installations keep their previous update behavior. See Community Release and update details.
How it fits together
Pi owns execution and native sessions. Harness observes each run and applies policies, budgets, checkpoints, recovery and evaluation around it. Agent teams use the same Pi execution engine. Conversation history and project architecture are workspace tools, and themes customize the look. 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"]
Native Pi and Pi-Harness, capability by capability
| 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 |
What it does
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. Opening Harness or Agents from Workspace Tools keeps 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. Git gives you diffs, history, activity graphs, commits, optional AI commit messages and worktrees.
![]() Lightweight file editing | ![]() Git |
Harness control plane
Every Pi run leaves a record you can inspect, compare and recover from.
| Observe | Runs, Trace, Replay, timelines and tool activity. Compare runs and follow forks and retries in the Run Tree |
| Measure | Tokens, cost and duration for each run, plus artifacts and project statistics |
| Control | Tool policies and per-run budgets. Create checkpoints, then resume, fork or retry work |
| Check | Evaluation, Diagnostics and regression baselines check results and investigate failures from recorded run evidence |
![]() Session status and queued instructions | ![]() Harness console |
Multi-agent orchestration
Open Workspace → Tools → Agents to 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 add review gates. Worktrees keep each agent's changes separate. Budgets, conflict hints, and pause, resume, abort, retry, skip and reassign controls help you manage the work.
![]() A sample team before execution: three idle agents, all tasks pending | ![]() Task dependencies and a review requirement |
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.
Open the original conversation read-only, 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 you ask for them.
![]() Conversation history | ![]() Session cleanup |
Project architecture map
Open Architecture in Workspace to explore modules, dependencies, entrypoints and source references. Filter by package, focus on a module, page through the map, zoom or go fullscreen. Save analysis snapshots, see when source changes make them stale, and export JSON, offline HTML or the current view as PNG.
| Local first | Analysis runs locally and uses no model tokens; AI descriptions are optional |
| Coverage | JavaScript, TypeScript and Vue imports are analyzed locally; other supported languages get a file-level index. Each analysis shows its coverage and limits |
| Scope | Maps describe supported static dependencies; they are not a complete function-call graph |
Providers, models and Skills
| Providers | Configure Pi-compatible providers with presets or custom endpoints, manage credentials, discover models where supported, test connections and choose your chat model. The Providers tab has shortcuts for ChatGPT, Claude, Gemini and the local gateway. |
| Sign in with ChatGPT | Connect your ChatGPT subscription in the browser and choose its models in chat. Manage each connected Codex account alongside API providers, see its remaining allowance and use a reset card when available. |
| Models, usage and quota | Filter configured models by provider, choose the default model and review recorded requests and token usage. The usage page also shows available API balances and subscription quotas. |
| Free Models | Choose a Kilo model directly in the chat model picker. No account or API key is required. Availability and limits depend on Kilo. The first selection shows a privacy notice. |
| Images | Use supported image models for text-to-image or image editing, then download the results |
| Skills | Browse built-in and local Skills and edit them. Type @ in the composer to search and invoke an installed Skill |
| Packages and extensions | Manage Pi packages and extensions from Capabilities. Optional add-ons such as Superpowers install, update or uninstall only when you choose |
![]() Providers and models | ![]() Capabilities |
![]() Sign in with ChatGPT | ![]() Free Models |
MCP servers and marketplace
Open Settings → MCP to add local-command or HTTP servers, filter by 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 has 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 there to install; they are not all enabled by default. Imported and registry entries are saved disabled, so you can finish configuring them first.
Agent settings
Available in v2.2.10 and later. Check the release notes for availability in downloaded installers.
| Page | What you set | |
|---|---|---|
| AI | Default thinking, automatic compaction, retry behavior and workspace preferences | Screenshot |
| Realtime voice | The voice service and account for workspace calls | Screenshot |
| Shortcuts | Your own shortcuts for the command palette, settings, new sessions and closing tabs, or the defaults | Screenshot |
| Instructions | Global or project instructions | Screenshot |
| MCP | MCP servers in each scope | Screenshot |
| Subagents | Reusable subagents with a role, instructions, model, thinking level and tools. Choose a shared workspace or an isolated worktree, then start a task or reuse the template in a team | Screenshot |
| Remote hosts | Hosts running pi-host, paired with an address and pairing token | Screenshot |
Realtime voice
Talk to your workspace with OpenAI Realtime, Gemini Live or Codex Live. 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.
- Open Settings → Realtime voice, enable voice, choose the service and account, and save.
- In a workspace conversation, click the waveform button beside the composer.
- Review the target conversation and optional context sharing, select Start realtime voice and allow microphone access.
- Mute, view transcripts or end the call from the floating controls, even after you move to another page.
Sharing recent context is off by default. When you turn it on, it includes only the last six plain-text messages, without attachments or tool results. Work requests from a call are sent to the work conversation only after you review them.
Remote hosts
Pair a host running pi-host from Settings → Remote hosts with 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.
Desktop companion
Enable an installed desktop pet in Settings → Desktop Pet to see thinking, tool activity, waiting and completion feedback on your desktop. It is off by default and stays available when the main window is minimized.
While idle, choose from 193 actions in a searchable right-click menu. During tasks, manual interactions pause, and dragging keeps the task animation going. Import local pet packs and adjust size, opacity and bubbles with sliders.
![]() Settings and sliders | ![]() Context menu | ![]() Searchable actions |
Themes and custom skins
Choose classic palettes, Ming themes, Starship Cockpit, macOS 27 backgrounds or an imported custom skin. New installations start in Soft Light. Customize chat display names, app icons, local background images, window and screen glow, and the input flame effect. A startup animation accompanies the environment check.
Character themes and desktop pets are optional packs. Open Settings → Resource Market to install one @piharness pack at a time from the GitHub catalog. The app starts without a network connection. A previously selected theme or pet is kept while its files are not installed yet, and the workspace uses the base appearance until you install that pack. See docs/market/MARKET.md.
Create your own skin with the Pi-Harness Custom Skin Starter:
- Use the starter repository as a template, or download it.
- Open it with your coding agent and describe the style you want with the included prompt.
- Import the finished 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 on its own.
![]() Ming · Snowbound official | ![]() Ming · Snow flute scholar |
![]() Ming · Moon scholar | ![]() Starship Cockpit |
![]() Ming · General settings | ![]() Ming · Theme and skin gallery |
![]() macOS 27 · Liquid Ether | |
Harness plugins
Plugin SDK v1.0.0 · Included starting with Pi-Harness v2.2.6. Plugins extend the operations around the agent, next to the ways Pi itself is extended:
| 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
Also
- Environment checks: check Node.js, npm, PATH, Pi Coding Agent and the active configuration; install, update or repair Pi where supported, inspect diagnostics and manage configuration backups.
- Runtimes: the bundled Pi and Node runtimes work out of the box, with System and Custom runtime choices in settings.
- App updates: check for new versions from inside the app.
- Eight languages: English, 简体中文, 繁體中文, 日本語, 한국어, Русский, Français and Deutsch.
Documentation
| Agent settings guide | AI, realtime voice, shortcuts, instructions, MCP, subagents and remote hosts |
| Resource Market | Install theme and desktop pet packs |
| Harness plugins | Develop and install plugins; see also architecture, SDK API and security boundary |
| Community Release | How community builds are signed, verified and updated |
| Troubleshooting | Checksum, security warning, launch and update problems |
| Screenshot index | Every interface and theme, by category |
| Changelog | What changed in each release |
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
To develop 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.
Before sending a change, run the checks. For changes to key desktop flows, also run pnpm test:e2e.
pnpm typecheck
pnpm lint
pnpm test
pnpm compile
Community
- Issues: report a bug or suggest an improvement. Include your app version, operating system and steps to reproduce, and remove credentials and private conversation content.
- Pull requests: describe the problem, the user-visible change and your validation results. Documentation, translations, themes and focused fixes are welcome.
- Custom skins: create a skin and share it.
- QQ group: pi-harness · 1109717308
If Pi-Harness makes your work with Pi easier, a ⭐ helps others find it.
Credits
Pi-Harness is built around the official Pi Coding Agent and Pi Agent Harness. Created and maintained by wangmiao · [email protected].
PR contributors
We welcome pull requests that improve Pi-Harness. Thank you to every contributor for helping make the project better!
License
GNU Affero General Public License v3.0 only (AGPL-3.0-only).
Copyright © 2026 wangmiao.
























