pi-until

Session-scoped shell-condition watches and recurring agent follow-ups for Pi.

Packages

Package details

extension

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

npm repo report

$ pi install npm:pi-until

Package: pi-until
Version: 0.1.5
Published: Oct 2, 2026
Downloads: 1,101/mo · 34/wk
Author: brettinternet
License: MIT
Types: extension
Size: 113.7 KB
Dependencies: 1 dependency · 4 peers

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ]
}

Security note

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

README

pi-until

Watch shell conditions and schedule recurring follow-ups without blocking Pi. A condition succeeds when it exits 0. Checks run in the background without model turns.

pi install npm:pi-until

Use a watch when a condition may become true before its timeout. For a fixed delay, use /wait from pi-wait instead of polling the clock.

Watch a condition

until({
  action: "start",
  condition: "test -f .deploy-finished",
  label: "deployment",
  intervalSeconds: 30,
  wake: "agent", // or "notify" to report without waking the agent
});

Repeat a follow-up

until({
  action: "repeat",
  instruction: "Review deployment logs and fix failures.",
  quickRef: "Deploy check",
  intervalSeconds: 3600,
  timeoutSeconds: 86400,
});

Finishing a turn doesn't complete recurring work. End it explicitly:

until({ action: "complete", id: "8f2c1a7d" });
until({ action: "cancel", id: "8f2c1a7d" });

Commands

/until start test -f .deploy-finished
/until list
/until status <id>
/until complete <id>
/until cancel <id>
/until stats

Lifecycle

Event	Result
Agent turn ends	Watches continue
`/reload`	Watches, delivery state, and receipts restore
`/new`, `/resume`, `/fork`	Watches stop
Pi exits or the machine reboots	Watches stop
Print or JSON mode	New watches are rejected

Use a durable scheduler for work that must outlive Pi.

Safety

Checks run through the shell with Pi's permissions, so installing this grants shell access even when Pi's shell tool is disabled. Use idempotent, side-effect-free commands. Output is discarded, checks time out, and cancellation kills the process group on macOS and Linux. Keep secrets out of conditions, labels, instructions, and context references.

Telemetry

Off by default:

PI_UNTIL_TELEMETRY=1 PI_UNTIL_TELEMETRY_FILE=/path/events.jsonl pi

Logs record watch metadata and 12-character condition hashes, never command text or instructions. They rotate at 5 MiB with one backup.

Development

bun install
bun run check
bun test test/until

Derived from Joel Hooks' pi-until. See LICENSE.