pi-harness

Observe, control, and orchestrate native Pi agents in one desktop workspace.

Automatically checked · GitHub checked 2026-11-15

Overview

Pi-Harness

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

Release Stars CI License
macOS Windows Linux

Download  ·  Watch  ·  Features  ·  Harness Plugins  ·  Docs  ·  Changelog

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


The Pi-Harness workspace: conversations, project files and Git in one window

赞助商

Pi-Harness × Infistar.cc 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 Pi-Harness × TokenArmy
Claude Pro 日租 · 独享账号,低至 $1.34/天,不封号
Claude API 按量计费 · 低至官方价格 1.25 折,失败不扣费
Pi-Harness 用户专属注册链接
价格与服务以 TokenArmy 平台规则为准。
腾讯云 WorkBuddy 【腾讯云】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.

Open video on GitHub

Welcome back. The companion appears and the workspace overview opens. 11 seconds.

Open video on GitHub

Quick start

1 · Install. Download the installer for your system from GitHub Releases:

macOSThe .dmg for Apple Silicon (arm64) or Intel (x64). Open it and drag Pi-Harness to Applications
WindowsThe x64 .exe installer. Run it and choose an installation directory
LinuxThe 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
CapabilityNative PiPi-Harness
Agent RuntimeYesNative Pi
Agent LoopYesNative Pi
SessionsYesYes + visual management
ContextYesYes + inspection
CompactionYesYes + visual control
SteeringYesYes
Follow-upYesYes
ModelsYesYes + manager
ThinkingYesYes + visual control
ToolsYesYes + selection and policy
SkillsYesYes + manager
ExtensionsYesYes + manager
PackagesYesYes + manager
MCP / CodemodeYesYes + 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
Lightweight file editing
Git diffs, history and commits
Git

Harness control plane

Every Pi run leaves a record you can inspect, compare and recover from.

ObserveRuns, Trace, Replay, timelines and tool activity. Compare runs and follow forks and retries in the Run Tree
MeasureTokens, cost and duration for each run, plus artifacts and project statistics
ControlTool policies and per-run budgets. Create checkpoints, then resume, fork or retry work
CheckEvaluation, Diagnostics and regression baselines check results and investigate failures from recorded run evidence
Harness: session status and queued instructions
Session status and queued instructions
Harness console
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 configured team before execution
A sample team before execution: three idle agents, all tasks pending
Pending tasks with dependencies and a review requirement
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
Conversation history
Session cleanup
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 firstAnalysis runs locally and uses no model tokens; AI descriptions are optional
CoverageJavaScript, TypeScript and Vue imports are analyzed locally; other supported languages get a file-level index. Each analysis shows its coverage and limits
ScopeMaps describe supported static dependencies; they are not a complete function-call graph
Project architecture map

Providers, models and Skills

ProvidersConfigure 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 ChatGPTConnect 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 quotaFilter 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 ModelsChoose 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.
ImagesUse supported image models for text-to-image or image editing, then download the results
SkillsBrowse built-in and local Skills and edit them. Type @ in the composer to search and invoke an installed Skill
Packages and extensionsManage Pi packages and extensions from Capabilities. Optional add-ons such as Superpowers install, update or uninstall only when you choose
Providers and models
Providers and models
Capabilities
Capabilities
Sign in with ChatGPT
Sign in with ChatGPT
Free Models
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.

MCP marketplace and built-in server templates

Agent settings

Available in v2.2.10 and later. Check the release notes for availability in downloaded installers.

PageWhat you set
AIDefault thinking, automatic compaction, retry behavior and workspace preferencesScreenshot
Realtime voiceThe voice service and account for workspace callsScreenshot
ShortcutsYour own shortcuts for the command palette, settings, new sessions and closing tabs, or the defaultsScreenshot
InstructionsGlobal or project instructionsScreenshot
MCPMCP servers in each scopeScreenshot
SubagentsReusable 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 teamScreenshot
Remote hostsHosts running pi-host, paired with an address and pairing tokenScreenshot

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.

  1. Open Settings → Realtime voice, enable voice, choose the service and account, and save.
  2. In a workspace conversation, click the waveform button beside the composer.
  3. Review the target conversation and optional context sharing, select Start realtime voice and allow microphone access.
  4. 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.

Workspace voice: setup and preparation before a call

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.

Desktop pet settings and sliders
Settings and sliders
Context menu
Context menu
Searchable action list
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:

  1. Use the starter repository as a template, or download it.
  2. Open it with your coding agent and describe the style you want with the included prompt.
  3. 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 · Snowbound official
Ming · Snow flute scholar
Ming · Snow flute scholar
Ming · Moon scholar
Ming · Moon scholar
Starship Cockpit
Starship Cockpit
Ming general settings
Ming · General settings
Theme and skin gallery
Ming · Theme and skin gallery
macOS 27 · Liquid Ether
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:

ExtensionPurpose
Pi ExtensionsExtend the Pi agent itself
SkillsGive the agent instructions and workflow knowledge
MCPConnect the agent to tools and external services
Harness PluginsExtend 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 guideAI, realtime voice, shortcuts, instructions, MCP, subagents and remote hosts
Resource MarketInstall theme and desktop pet packs
Harness pluginsDevelop and install plugins; see also architecture, SDK API and security boundary
Community ReleaseHow community builds are signed, verified and updated
TroubleshootingChecksum, security warning, launch and update problems
Screenshot indexEvery interface and theme, by category
ChangelogWhat 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.

Star history

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.