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/holdpty@0.4.0
• 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