pi-holdpty

Detached PTY sessions with regex pattern watching, exit notification, NDJSON event streaming, ownership/context tracking, and Pi extension wiring.

Lineage

This package is a fork of holdpty by Marc Fargas, originally released under the MIT License.

• Forked from: marcfargas/[email protected]
• License: MIT (preserved — see LICENSE)

What's new (delta from upstream)

| Feature | Command | Description | |---------|---------|-------------| | Regex/label watcher | holdpty watch <session> | Watch PTY output with regex patterns, debounce, coalescing, and NDJSON events | | Exit blocker | holdpty wait <session> | Block until session exits; returns child's exit code | | Unified NDJSON stream | holdpty tail-events <session\|all> | Merge match, exit, dropped, claim_change, and stale_warning events | | Ownership tracking | holdpty claim/release <session> | Single-writer PTY ownership with stale detection and force-claim | | Pi extension | — | Auto-injects active session context into Pi sessions |

Quick start

# Install
npm install pi-holdpty

# Launch a background session
holdpty launch --bg --name my-server -- node server.js

# Watch for errors
holdpty watch my-server --pattern ERROR

# Wait for exit
holdpty wait my-server

# Stream all events
holdpty tail-events my-server

# List sessions with ownership info
holdpty ls --json

Architecture

Layer 4 │ Pi extension          │ extensions/ — session_start hook, context render
Layer 3 │ CLI surface           │ dist/cli.ts — subcommand dispatch
Layer 2 │ Subsystems            │ line-filter, event-stream, ownership, staleness
Layer 1 │ Primitives (upstream) │ session, ring-buffer, protocol, client, holder, platform

See architecture.md in the plan directory for full design details.

Development

npm install
npm run build
npm test

License

MIT — see LICENSE