pi-better-harness

Pi extension bundle for an opt-in foreground write sandbox, subagents, durable background tasks, and goal tracking.

Packages

Package details

extension

Install pi-better-harness from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-better-harness
Package
pi-better-harness
Version
0.3.1
Published
Sep 5, 2026
Downloads
3,145/mo · 520/wk
Author
exoulster
License
MIT
Types
extension
Size
894.3 KB
Dependencies
4 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "extensions/sandbox/index.ts",
    "extensions/subagents/index.ts",
    "extensions/background-tasks/index.ts",
    "extensions/goal/index.ts"
  ],
  "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-harness.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-better-harness

pi-better-harness is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, and goal tracking.

Quick Answer

Use pi-better-harness when you want the full working set for Pi. It manages:

  • pi-better-sandbox for an opt-in write sandbox around Pi's foreground tools.
  • pi-better-subagents for detached, sandboxed subagent runs.
  • pi-better-background-tasks for durable shell tasks and watchers.
  • pi-better-goal for objective tracking that is aware of background work.

pi-better-read-aloud is intentionally not included yet.

Screenshots

Install

Install the extensions as standalone Pi packages, so Pi displays and manages each by its own package name:

npx pi-better-harness install

For project-local Pi settings:

npx pi-better-harness install --local

The bundled installation remains available for compatibility:

pi install npm:pi-better-harness

Ordinary Startup

You keep launching Pi the way you always have:

pi

The foreground write sandbox starts inactive. Use /sandbox on for the current session or /sandbox default on to persist opt-in across startup, new session, resume, fork, and reload. There is no launcher.

While it is on, Pi's built-in bash, write, and edit tools, your own ! / !! commands, local background tasks, and subagents can write only under the directory you launched Pi from, minus the packaged deny paths (.git/hooks, .env, .env.local).

Reads and network access are unrestricted — this sandbox limits writes only. Writes are confined for those integrated first-party execution paths; Pi's own process, arbitrary pi.exec calls, and unrelated third-party extension code are not confined. Confinement is also per surface: each integrated surface denies its own control plane, not every other surface's, so with several first-party surfaces installed a confined process on one can still write another's control plane.

Sandbox state is human-only: /sandbox, /sandbox on, /sandbox off, /sandbox default on|off, /sandbox deny ..., and /sandbox rules are slash commands with no tool equivalent. /sandbox off and /sandbox default off need interactive confirmation. Full policy: pi-better-sandbox.

When To Use

Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, or goal tracking.

Compatibility

Requirement Support
Pi Required
Recommended install npx pi-better-harness install
Write sandbox on macOS Seatbelt (sandbox-exec), ships with the OS
Write sandbox on Linux Bubblewrap — install bubblewrap
Development runtime Node.js 22+

Update Or Remove

Remove every standalone package:

npx pi-better-harness uninstall

Add --local to remove them from project-local settings.

More Detail