Process Tracker

Process Tracker

When enabled with --pid, Knightwatch tracks a root process and its entire child tree in real time, exposing snapshots via the /process family of endpoints. It also emits lifecycle events to the Telegram bot and webhook dispatcher.

knightwatch --pid <PID>

Pass --pid multiple times to track more than one root process simultaneously:

knightwatch --pid <PID1> --pid <PID2>

Endpoints

Endpoint	Description
GET /root_pids	List of all PIDs currently being tracked
GET /process/<PID>	Full snapshot — root info, child processes, and work_done flag
GET /process/root/<PID>	Root process snapshot only, or 404 if it has exited
GET /process/children/<PID>	Snapshots of all currently live child processes
GET /process/status/<PID>	Lightweight summary — alive/dead, child count, and work_done flag
GET /top-processes	Top N processes sorted by CPU or memory (requires --top-processes)

Process States

The state field on a process snapshot can be running, sleeping, gone, or any other platform string. Unknown states are rendered as a warning-colored pill in the dashboard.

Work-Done Detection

The work_done flag is set to true when all child processes of a tracked root have exited. The dashboard shows a completion banner at this point. The root process itself may still be running.

Webhook Events

Event	Description	Key data fields
process.initial_snapshot	First capture after startup	root, children, child_count
process.children_appeared	New child processes detected	pids, children
process.children_exited	One or more children exited	pids
process.all_children_gone	All children have exited	root_pid, root_name
process.root_exited	Root process exited	pid, name
process.work_complete	Work-done condition met	root_pid, root_name

Telegram Notifications

• 🟢 Initial snapshot — root and child count when tracking begins
• 🆕 Children appeared — new child PIDs detected
• 🔴 Children exited — specific child PIDs exited
• ✅ All children gone — all child processes have exited
• 💀 Root process exited — the root process itself has stopped