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, synchronous SSH commands, goal tracking, and structured plans.

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-ssh for short remote commands over reusable SSH connections.
• pi-better-goal for objective tracking that is aware of background work.
• pi-better-plan for persistent structured plans and explicit checklist progress.

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.

Minimal Tool Output

The bundled harness provides Tool output: Normal / Minimal in /harness-settings. /tool-output minimal, /tool-output normal, and /tool-output (toggle) remain compatibility shortcuts to the same preference. Minimal mode folds each tool call into a single-line header, including running calls. Muted tool names and quieter inline command/path context distinguish activity from conversation text; running and failed calls retain visible state markers. Long headers are truncated to the terminal width; result bodies, images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls are included. Execution, sandboxing, and agent-facing payloads are unchanged. In newer Pi fullscreen mode, click a folded row to expand its original details, then click the expanded call/result to collapse it. Regular terminals keep mouse input for terminal selection and scrollback; Ctrl+O expands tools in all modes. /tool-output normal restores ordinary rendering. Error result bodies are also hidden in minimal mode and remain available when expanded.

Normal mode is the default. The preference is saved in the current session, including resume/reload. This is a version-sensitive internal TUI adapter, tested with Pi 0.82.1, 0.99.1, and the bundled Pi 1.0.0 CLI; incompatible APIs produce a warning and leave ordinary output enabled. Print/RPC output and exported transcripts are unchanged.

The standalone-package installer does not install this bundled extension. Load the bundled harness or run it directly from a checkout:

pi -e ./packages/pi-better-harness/extensions/minimal-output/index.ts

Harness Settings

The bundled harness provides /harness-settings, using Pi's native settings list. It opens the settings screens of loaded Sandbox, Subagents, and Goal packages without duplicating their configuration. /sandbox, /subagents settings, and /goal settings remain available in standalone installations. Packages without a settings screen are not listed. Pi's /settings is unchanged.

The hub includes Tool output when the bundled renderer extension is loaded. Changes apply immediately to the current session and do not save a global default. The hub also owns Completions while busy, shared by Subagents and Background Tasks. Choose Wait until idle (the default) or Steer active run. Changes apply immediately and autosave to the current session branch, including across reloads. Press Ctrl+S to save the current choice as your default for future Pi sessions; changing a session afterward does not change that saved default. Saving a default leaves already-open sessions unchanged, including when navigating to a branch without a session override. The user default is stored in <agent-dir>/extensions/pi-better-callback-preferences.json and also applies when either callback package is loaded standalone. The former PI_BETTER_CALLBACK_WHILE_BUSY environment variable is no longer supported.

Next-prompt inference is deferred pending safe public auth/header resolution in Pi's SDK. It is not loaded by the bundle, has no toggle or preference store in this version, and makes no auxiliary model requests. The integration blocker is issue #426.

The hub is TUI-only. The standalone-package installer does not install Harness-only extensions; load the bundle or the settings extension from the checkout to use the hub:

pi -e ./packages/pi-better-harness/extensions/settings/index.ts

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, synchronous SSH, goal tracking, or plans.

Compatibility

Update Or Remove

Remove every standalone package:

npx pi-better-harness uninstall

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

More Detail

• Repository: https://github.com/1aboveio/pi-better-harness
• Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-harness/docs/usage.md
• License: https://github.com/1aboveio/pi-better-harness/blob/main/LICENSE