# pi-better-background-tasks `pi-better-background-tasks` is a Pi extension for durable background shell tasks, watchers, logs, and status inspection. ## Quick Answer Use `pi-better-background-tasks` when a command should keep running while the foreground Pi session stays free. It is best for dev servers, long scripts, queue watchers, deploy checks, log tails, and other command-driven work. ## Screenshots

pi-better-background-tasks rendered in Pipi-better-background-tasks package overview

## Core Features - Start long-running commands without blocking the current turn. - Watch commands until success, failure, or timeout. - Keep task metadata and logs available across reloads. - Show active work in Pi's background-work navigator. - Flag running tasks with no observable output or completed poll as stalled. - Confine local task writes to the project directory when `pi-better-sandbox` is enabled. ## Write Sandbox When [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme) is installed and enabled, every **local** task captures the effective foreground policy at launch and runs under the platform's write sandbox: reads and network stay unrestricted, writes are confined to the canonical project directory, and denied paths stay denied. The policy is captured once, when the task starts. A later `/sandbox on`, `/sandbox off`, or deny-rule change reaches tasks launched after it; a task already running — including a watcher resumed in a later Pi session — keeps the policy it started with. If the foreground sandbox reports `unavailable` or `failed`, a local launch is refused with an explanation instead of running unconfined. `/sandbox off` is the deliberate way to run local tasks unsandboxed. Structured remote SSH tasks are unaffected: the foreground sandbox describes this machine, and remote work keeps its existing remote semantics. Without `pi-better-sandbox` installed, local tasks behave exactly as they always have. Reads and network access are never restricted; only writes are. Pi's own process, `pi.exec` calls, and unrelated third-party extension code stay outside the guarantee, and confinement is per surface: a confined process on another first-party surface can still write this one's task registry. Installing [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme) brings the sandbox in by default, so an ordinary `pi` session confines its foreground tools and its local background tasks under one project policy. ## Remote SSH For short synchronous remote commands that should return output in the current turn, install `pi-better-ssh` and use `remote_bash`. Use background tasks for long-running or durable remote jobs and asynchronous health watches. Prefer structured `ssh` fields over hand-written `ssh` command lines. A remote spawn uses a durable tmux session by default, while a remote watch opens one direct SSH poll per interval and does not require tmux. The package keeps the same local metadata, logs, terminal statuses, callbacks, and `/reload` recovery for both. ```json { "name": "remote build", "command": "npm run build", "ssh": { "host": "build.example", "user": "deploy" }, "remote": { "workdir": "/srv/app" }, "timeout_seconds": 1800 } ``` Tmux-backed spawn can install tmux non-interactively when the remote host allows it and fails closed with copy-pasteable setup guidance when it cannot. Set `remote.session=direct` only as an explicit escape hatch for short jobs: stop or timeout can terminate the local SSH client but the remote process may still be running. See the detailed usage notes for bootstrap policy, watch conditions, timeouts, and v1 non-goals. ## Install ```sh pi install npm:pi-better-background-tasks ``` Try it for one run: ```sh pi -e npm:pi-better-background-tasks ``` ## When To Use Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn. Do not use it for short commands where the foreground session should wait for the result directly; use `remote_bash` from `pi-better-ssh` instead. ## Compatibility | Requirement | Support | |-------------|---------| | Pi | Required | | Install method | `pi install npm:pi-better-background-tasks` | | Development runtime | Node.js 22+ | ## Update Or Remove ```sh pi update npm:pi-better-background-tasks pi remove npm:pi-better-background-tasks ``` ## More Detail - Repository: https://github.com/1aboveio/pi-better-harness - Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-background-tasks/docs/usage.md - License: https://github.com/1aboveio/pi-better-harness/blob/main/LICENSE