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
Что это такое?Pi-Harness — это настольное приложение, расширяющее Pi Coding Agent: оно добавляет к нативному Pi визуальное рабочее пространство, наблюдаемость, управление политиками, восстановление, оценку качества и оркестрацию нескольких агентов, оставаясь при этом полностью совместимым с сессиями и Skills Pi.
Это отдельное приложение или плагин для Pi?Это самостоятельное настольное приложение на Electron/Vue3 для macOS, Windows и Linux, которое оборачивает и расширяет рантайм нативного Pi Coding Agent графическим интерфейсом, а не библиотека кода или плагин для редактора.
Как его запустить?Скачайте готовый установщик для своей ОС со страницы GitHub Releases — .dmg для macOS (arm64 или x64), .exe для Windows x64 или .AppImage для Linux x64 — затем запустите его и проверьте окружение в разделе Overview.
Нужно ли сначала отдельно установить Pi Coding Agent?Нужен нативный Pi Coding Agent, но Pi-Harness может сам установить или починить его прямо из приложения; если же собирать из исходников, потребуется Node.js ≥ 22.22.2 и pnpm 9.12.1.
Есть ли подводные камни при установке?Неподписанные community-сборки для macOS при первом запуске могут быть заблокированы — тогда их нужно разрешить через System Settings → Privacy & Security → Open Anyway. Кроме того, карта архитектуры даёт полный анализ зависимостей только для JavaScript, TypeScript и Vue — для остальных языков доступен лишь индекс файлов.
На каких системах он работает?Поддерживаются macOS на Apple Silicon, macOS на Intel, Windows x64 и Linux x64.
Просмотр моих прошлых диалогов с агентом тратит токены модели?Нет — просмотр локальной истории диалогов, превью и анализ архитектуры проекта выполняются локально и не расходуют токены модели; ИИ-сводки и описания запускаются только по вашему явному запросу.
Что Pi-Harness добавляет к нативному Pi Coding Agent?Поверх всего, что уже умеет нативный Pi, он добавляет инспекцию запусков (Trace, Replay, Run Compare), политики для инструментов, бюджеты на запуск, чекпоинты, оценку качества, диагностику и оркестрацию задач нескольких агентов с изоляцией в worktree.
Можно ли импортировать историю из других кодинг-агентов?Да, он умеет просматривать и искать по локальной истории диалогов Claude Code, Codex, Cursor, Cursor Agent, Gemini CLI и OpenCode наряду с историей самого Pi, а также позволяет продолжить прошлый диалог как новый чат Pi.
Можно настроить его внешний вид?Да, в комплекте темы classic, Ming, Starship Cockpit и macOS 27, плюс поддержка импорта собственной темы, собранной по шаблону Pi-Harness Custom Skin Starter.
Как работает оркестрация задач нескольких агентов?Вы управляете переиспользуемыми командами агентов и шаблонами, назначаете задачи с зависимостями и приоритетами, запускаете их вручную, последовательно или параллельно и управляете ими через ревью-гейты, изоляцию в worktree и паузу/возобновление/повтор.
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.1Oct 18
Age
1mo
Commits · 90 Days