pi-watch-process
Pi extension to manage CLI watch-mode processes (tsc --watch, jest --watch, etc.)
Package details
Install pi-watch-process from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-watch-process- Package
pi-watch-process- Version
1.1.3- Published
- Nov 21, 2026
- Downloads
- 354/mo · 38/wk
- Author
- tychenjiajun
- License
- MIT
- Types
- extension
- Size
- 60.4 KB
- Dependencies
- 0 dependencies · 2 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-watch-process
Pi extension for managing CLI watch-mode processes. Start, monitor, hot-restart, and control long-running commands like tsc --watch, jest --watch, or cargo watch directly from the LLM — or from a codemode script.
Installation
Place in an auto-discovery location or use --extension:
# Quick test
pi -e /path/to/pi-watch-process/index.ts
# Global install
ln -s ~/projects/pi-watch-process ~/.pi/agent/extensions/watch-process
# Project-local
mkdir -p .pi/extensions
ln -s ~/projects/pi-watch-process .pi/extensions/watch-process
Or configure via settings.json:
{
"extensions": ["/path/to/pi-watch-process"]
}
Tools
Once loaded, 8 tools are available to the LLM and to codemode scripts.
| Tool | Description | Key Parameters |
|---|---|---|
watch_start |
Start a process | {command, args[], cwd?, name?, bufferSize?} |
watch_stop |
Stop a process by ID or name | {process} |
watch_restart |
Hot-restart in place (keeps ID, name, history) | {process} |
watch_list |
List all tracked processes | {includeCompleted?} |
watch_status |
Detailed status of one process | {process} |
watch_output |
Get recent output (unread lines by default) | {process, since_seq?, since_seconds_ago?, limit?, sources?} |
watch_wait |
Block until output arrives or a match is found | {process, since_seq?, since_seconds_ago?, timeout_ms?, match?, matchRegex?, sources?} |
watch_input |
Send text to stdin | {process, text} |
watch_output and watch_wait default to the process read cursor, so they
include output buffered before the call instead of skipping it. Both return
next_seq; pass it back as since_seq to read only newer lines.
Example workflow
1. Start a TypeScript watcher:
{ "name": "watch_start", "arguments": { "command": "tsc", "args": ["--watch"], "cwd": "/path/to/project", "name": "tsc" } }
// → Started process proc_1 (tsc). PID: 12345
2. Wait for compilation to finish:
{ "name": "watch_wait", "arguments": { "process": "proc_1", "match": "Found X error(s)", "timeout_ms": 30000 } }
3. Poll incremental output:
{ "name": "watch_output", "arguments": { "process": "tsc", "since_seq": 42, "limit": 50 } }
Omit since_seq to read from the process read cursor (unread lines); the result
carries next_seq for the next call. watch_wait uses the same default, so a
cycle that already finished (e.g. right after watch_start) matches immediately
instead of timing out.
Vitest v3/v4: when spawned without a TTY,
vitestruns once and exits. Pass--watchexplicitly (args: ["vitest", "--watch", "<filter>"]) so the watcher stays alive.
4. Hot-restart after editing a watched config:
{ "name": "watch_restart", "arguments": { "process": "tsc" } }
Codemode
Every tool declares an outputSchema and returns structuredContent, so codemode scripts receive data instead of parsing text. Success results are { ok: true, ... }; failures come back with isError: true and { ok: false, error }, so scripts branch without try/catch.
// Run a build, wait for it to settle, then inspect structured output — one script.
const started = tools.watch_start({ command: "tsc", args: ["--watch"], name: "tsc" });
if (!started.ok) throw new Error(started.error);
const wait = await tools.watch_wait({ process: started.process.id, match: "Found 0 errors", timeout_ms: 30000 });
const errors = tools.watch_output({ process: started.process.id, sources: ["stderr"] });
return {
pid: started.process.pid,
matched: wait.matched,
timed_out: wait.timed_out,
stderr: errors.lines.map((l) => l.text),
};
watch_wait is a real pending tool call, so it works inside the timer-less codemode sandbox. Because results are structured, scripts can fan out across several watchers and filter output before the model ever sees it.
Hot module replacement (HMR)
The extension is built to survive /reload:
- The process registry lives on
globalThis, not in module scope, so a reloaded runtime adopts the still-running children and their ring buffers instead of leaking or dropping them. - The
data/closehandlers attached by the previous runtime keep streaming into the same buffers, so no output is lost across a reload. - On
session_shutdownwith reasonreload, pendingwatch_waitlisteners are detached but the children are left running. On every other shutdown reason (quit,new,resume,fork) all children are killed. watch_restartis the in-process HMR primitive: stop and start a watcher in place while preserving its ID, name, and buffered history.
Features
- Multiple processes: run several watchers simultaneously (e.g. tsc + jest + cargo watch)
- Flexible identification: reference processes by auto-generated ID (
proc_1) or human-readable name (tsc) - Ring buffer: 500-line rolling buffer with sequence numbers and timestamps
- Flexible queries:
since_seqfor polling, orsince_seconds_agofor time-based queries - Blocking wait:
watch_waitblocks with substring or regex matching (ideal for "wait for build to finish") - Structured results: every tool has an
outputSchemafor codemode; the model still gets readable text - HMR-safe: reloads adopt running processes;
watch_restarthot-restarts in place - Stdin support: send input to interactive prompts via
watch_input - No persistence: all processes are killed on real session shutdown (fresh start each time)
- Abort-safe:
watch_waithonors the agent abort signal (Esc cancels the wait) - ANSI stripping: output is automatically cleaned of terminal escape codes
- Source tagging: each line is tagged as
stdout,stderr, orsystem
How it relates to LSP
This extension is complementary to a language server, not a replacement for it. See docs/vs-lsp.md for the full comparison — the short version is that LSP wins for precise, structured language diagnostics, while watch-process wins for anything that runs as a CLI (builds, tests, linters, dev servers) and for anything interactive.
Technical details
- No build required — TypeScript compiled on-the-fly via jiti
- Follows patterns from
pi-headless-subagent(state management, cleanup on shutdown) - Peer dependencies:
@earendil-works/pi-coding-agent,@sinclair/typebox - Pure Node.js implementation using
child_process.spawnandEventEmitter
License
MIT