Pi-Harness
Why Pi-Harness?
Pi-Harness is an operational superset of Pi Coding Agent.
It keeps Native Pi as the execution runtime and preserves Pi-compatible sessions, tools, models, Skills, extensions, context, and compaction, while adding a complete Harness engineering layer around it.
Pi-Harness adds:
- Observe — Runs, Trace, Replay, Diagnostics, Evaluation, Regression, and Artifacts
- Control — Policy, Budget, Checkpoints, Recovery, Permissions, and tool control
- Orchestrate — Agents, Teams, Tasks, Dependencies, Handoffs, Review Gates, and Worktrees
- Work — Workspace, Files, Git, Models, Providers, Skills, and Packages
Pi runs the agent. Pi-Harness turns Pi into a visible, controllable, recoverable, and orchestratable engineering system.
Pi-Harness does not replace or reimplement Pi's Agent Runtime.
What "Superset" Means
Native Pi remains inside the real execution path.
Pi Coding Agent
├── Agent Runtime
├── Sessions
├── Context
├── Tools
├── Models
├── Thinking
├── Compaction
├── Skills
└── Extensions
⊂
Pi-Harness
├── Everything above through Native Pi
├── Runs / Trace / Replay
├── Policy / Budget
├── Checkpoints / Recovery
├── Evaluation / Diagnostics
├── Regression / Artifacts
├── Multi-Agent Orchestration
├── Tasks / DAG / Handoffs
├── Review Gates / Worktrees
└── Visual Engineering Workspace
Core Capabilities
| Layer | Capabilities |
|---|---|
| Native Pi Runtime | Agent Runtime, Sessions, Context, Tools, Models, Thinking, Compaction, Skills, Extensions |
| Observe | Runs, Trace, Replay, Run Compare, Diagnostics, Evaluation, Regression, Artifacts |
| Control | Policy, Budget, Checkpoints, Recovery, Permissions, tool control, Compaction |
| Orchestrate | Agents, Teams, Tasks, Dependencies, Handoffs, Review Gates, Worktree isolation |
| Work | Workspace, Files, Git, Worktrees, Models, Providers, Skills, and Packages |
What's new in v1.8.1
@Skillin the composer — Type@to search installed Skills, navigate suggestions from the keyboard, and invoke the selected Skill through Native Pi.- Compact Skill history — Expanded Skill prompts stay concise in conversations, full history, and restored session titles.
- Cleaner Workspace controls — Skill suggestions, file-panel view controls, and sidebar actions use a tighter visual hierarchy with less chrome.
Startup and appearance
Pi-Harness opens with a startup animation while it checks the npm registry, Node.js, npm, Pi Agent, and the active configuration. The animation remains visible for at least five seconds, uses a monochrome quantum particle effect by default, and follows the selected optional visual theme when one is active.
New installations use macOS 27 Dark with the Liquid Ether background. In Settings → General, choose another palette or macOS 27 background, use a local PNG/JPEG/WebP background, customize chat display names, choose the Classic, Ming, or Quantum app icon, and control the window glow, screen glow, and input flame effect independently.
In Settings → Theme, the built-in themes remain available alongside declarative custom skins. Pi-Harness can create a constrained skin starter project for Codex or Pi and import its local bitmap assets and color tokens. Mascot-free builds keep the default startup animation and General appearance controls without loading optional portrait themes.
Create your own custom skin
Use the Pi-Harness Custom Skin Starter to create a skin in any visual style you like:
- Use the starter repository as a template or download it.
- Open it with Codex or Pi and describe your preferred style using the included copy-and-run prompt or
SKIN_BRIEF.md. - Import the completed project from Settings → Theme → Import Skin.
The multilingual starter includes the manifest schema, editable color tokens, asset requirements, and validation instructions for the preview, wallpaper, and optional portrait. Keep the skin in its own repository to version, update, and share it independently from Pi-Harness.
Optional methodologies and add-ons
Native Pi remains the built-in default runtime and workflow. Pi-Harness does not replace it and does not silently install or enable third-party methodologies.
- Superpowers is the recommended optional add-on: a complete software development methodology for coding agents covering brainstorming, planning, TDD, systematic debugging, Git worktrees, subagent and parallel-agent workflows, code review, and verification. Install it explicitly from Capabilities with
pi install git:github.com/obra/superpowers. - Odai remains an optional governance and adaptive-execution methodology for goal alignment, authorization boundaries, risk awareness, capability routing, evidence, and verification.
Both add-ons use the existing trusted capability/package management flows and can be updated or removed independently.
Lightweight editor, not an IDE
Pi-Harness edits readable text with lazy syntax highlighting, line numbers, undo/redo, find, explicit save, unsaved-state indicators, and external-change conflict protection. Oversized, binary, media, and document files use read-only previews.
It deliberately does not include LSP/IntelliSense, semantic refactoring, a debugger, task runner, integrated terminal, or IDE extension compatibility.
Current screenshots
The classic dark screenshots show the core product surfaces. The v1.8.1 gallery shows the refreshed Ming themes, Starship Cockpit, macOS 27 Liquid Glass, custom skins, and appearance settings.
Classic dark theme
| Workspace | Git |
|---|---|
 |
 |
| Capabilities | Models |
 |
 |
| Preferences | |
 |
v1.8.1 appearance gallery
Workspace themes
| Ming · Snowbound official | Ming · Snow flute scholar |
|---|---|
 |
 |
| Ming · Moon scholar | Starship Cockpit |
 |
 |
| macOS 27 · Liquid Ether | Declarative skin |
 |
 |
Product interfaces
| **Ge