{"_id":"@awesamarth/watchdog","_rev":"5-6abb8596adbdd70b8ba5ac502d5143d9","name":"@awesamarth/watchdog","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@awesamarth/watchdog","version":"0.1.0","keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"author":{"name":"awesamarth"},"license":"MIT","_id":"@awesamarth/watchdog@0.1.0","maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"homepage":"https://github.com/awesamarth/watchdog#readme","bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"pi":{"extensions":["./dist/pi-extension.js"]},"bin":{"watchdog":"dist/cli.js"},"dist":{"shasum":"b6e4ee9989b964dc7b65bbb68ca63b685bbf0ee3","tarball":"https://registry.npmjs.org/@awesamarth/watchdog/-/watchdog-0.1.0.tgz","fileCount":34,"integrity":"sha512-5Nygq7m7r4g5Q4s7LhlTsOpxbdtVlV60cKZrAEJz+ez8w2CXLLFyao1DR0fVjcZmLbaVQOgqcdKSDk9Sl1iOXQ==","signatures":[{"sig":"MEQCIEoZWSraAaWWRbCoueC4y7uC/Bag4iykQ4CslFrdoDkmAiBM/CXUQsePvKBCwsYXMT1grP267UZ6Z57FDydVv53RAg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8491217},"type":"module","engines":{"node":">=22"},"gitHead":"fc2bd3be2d71cd81468cf859dd9cea3e3e4cb521","scripts":{"dev":"tsx src/cli.ts","demo":"bun run web:build && tsx src/cli.ts demo","test":"vitest run src web/src","build":"bun run web:build && tsup","check":"tsc --noEmit && tsc -p web/tsconfig.json --noEmit","web:dev":"vite --config web/vite.config.ts","test:web":"playwright test","dashboard":"bun run web:build && tsx src/cli.ts dashboard","web:build":"vite build --config web/vite.config.ts"},"_npmUser":{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"},"repository":{"url":"git+https://github.com/awesamarth/watchdog.git","type":"git"},"_npmVersion":"11.6.2","description":"Control subagents, agentic loops, and execution graphs from one local command center.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.1","ink":"^7.1.0","zod":"^4.4.3","sirv":"^3.0.2","react":"^19.2.7","typebox":"1.1.38","remark-gfm":"^4.0.1","react-markdown":"^10.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.14","devDependencies":{"tsx":"^4.19.3","tsup":"^8.5.0","vite":"^8.1.4","vitest":"^3.1.2","@types/ws":"^8.5.14","react-dom":"^19.2.7","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^19.2.17","@playwright/test":"^1.61.1","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.3","@earendil-works/pi-coding-agent":"^0.80.10"},"_npmOperationalInternal":{"tmp":"tmp/watchdog_0.1.0_1784589419455_0.18117831421765684","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@awesamarth/watchdog","version":"0.1.1","keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"author":{"name":"awesamarth"},"license":"MIT","_id":"@awesamarth/watchdog@0.1.1","maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"homepage":"https://github.com/awesamarth/watchdog#readme","bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"pi":{"extensions":["./dist/pi-extension.js"]},"bin":{"watchdog":"dist/cli.js"},"dist":{"shasum":"19a303792fec4e6ee127101cab0029f4bb1e19aa","tarball":"https://registry.npmjs.org/@awesamarth/watchdog/-/watchdog-0.1.1.tgz","fileCount":33,"integrity":"sha512-IWEm1ysniWHkxe+w6ltkmhjgEeepkEBnZqSJNgJ+oB7pKy+TqSqhCZDGR1gSeZ3qnUEFeRtWWdV0COo0MpfCVg==","signatures":[{"sig":"MEYCIQDCUmeSfanxlbKVCreeypTIIYAENkLPS3T5HPV9gWT8/QIhANyhLH7Q76dQW9xs4RZ+edSJc5MvlchKT2V12soJoZWy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2437915},"type":"module","engines":{"node":">=22"},"gitHead":"e8f27b7d7a727a08c5af94774759f246be6861b4","scripts":{"dev":"tsx src/cli.ts","test":"vitest run src web/src","build":"bun run web:build && tsup","check":"tsc --noEmit && tsc -p web/tsconfig.json --noEmit","web:dev":"vite --config web/vite.config.ts","test:web":"playwright test","dashboard":"bun run web:build && tsx src/cli.ts dashboard","web:build":"vite build --config web/vite.config.ts"},"_npmUser":{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"},"repository":{"url":"git+https://github.com/awesamarth/watchdog.git","type":"git"},"_npmVersion":"11.6.2","description":"Control subagents, agentic loops, and execution graphs from one local command center.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.1","ink":"^7.1.0","zod":"^4.4.3","sirv":"^3.0.2","react":"^19.2.7","typebox":"1.1.38","remark-gfm":"^4.0.1","react-markdown":"^10.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.14","devDependencies":{"tsx":"^4.19.3","tsup":"^8.5.0","vite":"^8.1.4","vitest":"^3.1.2","@types/ws":"^8.5.14","react-dom":"^19.2.7","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^19.2.17","@playwright/test":"^1.61.1","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.3","@earendil-works/pi-coding-agent":"^0.80.10"},"_npmOperationalInternal":{"tmp":"tmp/watchdog_0.1.1_1784643275720_0.4969692852089729","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@awesamarth/watchdog","version":"0.1.2","keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"author":{"name":"awesamarth"},"license":"MIT","_id":"@awesamarth/watchdog@0.1.2","maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"homepage":"https://github.com/awesamarth/watchdog#readme","bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"pi":{"extensions":["./dist/pi-extension.js"]},"bin":{"watchdog":"dist/cli.js"},"dist":{"shasum":"d6368acb8aa9a1f8ba93d0404370ad98ba4fc51c","tarball":"https://registry.npmjs.org/@awesamarth/watchdog/-/watchdog-0.1.2.tgz","fileCount":33,"integrity":"sha512-Lqn9Uf9exljvT2VUIp0XvXjdBZwlSh/Klt2Lb+nfMPh7R2MZ9/0+JnhInLxu8JzQADx4Mx/dy4U01DwJOS02zQ==","signatures":[{"sig":"MEQCICFkM7hpODsU8NibOqD+nd5CvjEX9apfFp7+QNe5WPQ0AiBrZt531qUj1fa7qvWaatEkO00dYKdLBIg/mDbZCfW7UA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2440965},"type":"module","engines":{"node":">=22"},"gitHead":"1bead764dcedced75314f0fb9ab15542e5f88f6b","scripts":{"dev":"tsx src/cli.ts","test":"vitest run src web/src","build":"bun run web:build && tsup","check":"tsc --noEmit && tsc -p web/tsconfig.json --noEmit","web:dev":"vite --config web/vite.config.ts","test:web":"playwright test","dashboard":"bun run web:build && tsx src/cli.ts dashboard","web:build":"vite build --config web/vite.config.ts"},"_npmUser":{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"},"repository":{"url":"git+https://github.com/awesamarth/watchdog.git","type":"git"},"_npmVersion":"11.6.2","description":"Control subagents, agentic loops, and execution graphs from one local command center.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.1","ink":"^7.1.0","zod":"^4.4.3","sirv":"^3.0.2","react":"^19.2.7","typebox":"1.1.38","remark-gfm":"^4.0.1","react-markdown":"^10.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.14","devDependencies":{"tsx":"^4.19.3","tsup":"^8.5.0","vite":"^8.1.4","vitest":"^3.1.2","@types/ws":"^8.5.14","react-dom":"^19.2.7","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^19.2.17","@playwright/test":"^1.61.1","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.3","@earendil-works/pi-coding-agent":"^0.80.10"},"_npmOperationalInternal":{"tmp":"tmp/watchdog_0.1.2_1784647335942_0.833004397698512","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@awesamarth/watchdog","version":"0.1.3","keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"author":{"name":"awesamarth"},"license":"MIT","_id":"@awesamarth/watchdog@0.1.3","maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"homepage":"https://github.com/awesamarth/watchdog#readme","bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"pi":{"extensions":["./dist/pi-extension.js"]},"bin":{"watchdog":"dist/cli.js"},"dist":{"shasum":"bc186442bf31bddf579f082575b127278a0b84a6","tarball":"https://registry.npmjs.org/@awesamarth/watchdog/-/watchdog-0.1.3.tgz","fileCount":33,"integrity":"sha512-6nW/ttKZ8Pb5nvCjmUyyWOPcoVtjiThI2U/OzYXwmfZR7ta0i1ROtzuEDHAaO4EX/9isU6ixQIeOtJrKb93GTg==","signatures":[{"sig":"MEUCIFMOhnfhz3UkDKuLQ0ggDcytaOCM7Y1Qu+r9CfxndBUnAiEAjKK/AbJoeOliKTMcvJsWjPl66Bj9+1skf7pC6aUGbxo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2441201},"type":"module","engines":{"node":">=22"},"gitHead":"1bead764dcedced75314f0fb9ab15542e5f88f6b","scripts":{"dev":"tsx src/cli.ts","test":"vitest run src web/src","build":"bun run web:build && tsup","check":"tsc --noEmit && tsc -p web/tsconfig.json --noEmit","web:dev":"vite --config web/vite.config.ts","test:web":"playwright test","dashboard":"bun run web:build && tsx src/cli.ts dashboard","web:build":"vite build --config web/vite.config.ts"},"_npmUser":{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"},"repository":{"url":"git+https://github.com/awesamarth/watchdog.git","type":"git"},"_npmVersion":"11.6.2","description":"Control subagents, agentic loops, and execution graphs from one local command center.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.1","ink":"^7.1.0","zod":"^4.4.3","sirv":"^3.0.2","react":"^19.2.7","typebox":"1.1.38","remark-gfm":"^4.0.1","react-markdown":"^10.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.14","devDependencies":{"tsx":"^4.19.3","tsup":"^8.5.0","vite":"^8.1.4","vitest":"^3.1.2","@types/ws":"^8.5.14","react-dom":"^19.2.7","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^19.2.17","@playwright/test":"^1.61.1","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.3","@earendil-works/pi-coding-agent":"^0.80.10"},"_npmOperationalInternal":{"tmp":"tmp/watchdog_0.1.3_1784657689126_0.941785236407837","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@awesamarth/watchdog","version":"0.1.4","description":"Control subagents, agentic loops, and execution graphs from one local command center.","license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/awesamarth/watchdog.git"},"homepage":"https://github.com/awesamarth/watchdog#readme","bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"author":{"name":"awesamarth"},"keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"packageManager":"bun@1.3.14","type":"module","bin":{"watchdog":"dist/cli.js"},"pi":{"extensions":["./dist/pi-extension.js"]},"scripts":{"dev":"tsx src/cli.ts","dashboard":"bun run web:build && tsx src/cli.ts dashboard","web:dev":"vite --config web/vite.config.ts","web:build":"vite build --config web/vite.config.ts","build":"bun run web:build && tsup","check":"tsc --noEmit && tsc -p web/tsconfig.json --noEmit","test":"vitest run src web/src","test:web":"playwright test"},"engines":{"node":">=22"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","ink":"^7.1.0","react":"^19.2.7","react-markdown":"^10.1.0","remark-gfm":"^4.0.1","sirv":"^3.0.2","typebox":"1.1.38","ws":"^8.18.1","zod":"^4.4.3"},"devDependencies":{"@earendil-works/pi-coding-agent":"^0.80.10","@playwright/test":"^1.61.1","@types/node":"^22.15.3","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","@types/ws":"^8.5.14","@vitejs/plugin-react":"^6.0.3","react-dom":"^19.2.7","tsup":"^8.5.0","tsx":"^4.19.3","typescript":"^5.8.3","vite":"^8.1.4","vitest":"^3.1.2"},"gitHead":"52d03f7e9d3414efc52ee2e994ae5456547cb433","_id":"@awesamarth/watchdog@0.1.4","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-RcTOQXkatXiGf2BYZHHS3MZ1PQaB2YbxXQB5YPVGiFgnyCZccP4MkjXWrlhtr5t8sw8Ba3RSevn5mSikpVg5+g==","shasum":"5939034b99361f941327626e54a63aecc3b238af","tarball":"https://registry.npmjs.org/@awesamarth/watchdog/-/watchdog-0.1.4.tgz","fileCount":33,"unpackedSize":2442256,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEjNjqTGnP0I0mGQJS5clNtyJHC6cmEdxKcWS88kzln5AiEA2npwC/l0I5Jj05Hgg5k5fCirNBDcM8mdVvcDcXoSJc8="}]},"_npmUser":{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"},"directories":{},"maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/watchdog_0.1.4_1784661555631_0.7338161370031044"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T23:16:59.337Z","modified":"2026-07-21T19:19:16.009Z","0.1.0":"2026-07-20T23:16:59.771Z","0.1.1":"2026-07-21T14:14:35.919Z","0.1.2":"2026-07-21T15:22:16.118Z","0.1.3":"2026-07-21T18:14:49.400Z","0.1.4":"2026-07-21T19:19:15.855Z"},"bugs":{"url":"https://github.com/awesamarth/watchdog/issues"},"author":{"name":"awesamarth"},"license":"MIT","homepage":"https://github.com/awesamarth/watchdog#readme","keywords":["agents","codex","pi","subagents","agentic-loops","observability","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/awesamarth/watchdog.git"},"description":"Control subagents, agentic loops, and execution graphs from one local command center.","maintainers":[{"name":"awesamarth","email":"samarthsaxena1672003@gmail.com"}],"readme":"# Watchdog\n\n**Control subagents, agentic loops, and execution graphs from one local command center.**\n\n[![npm](https://img.shields.io/npm/v/%40awesamarth%2Fwatchdog?color=f2bf4f)](https://www.npmjs.com/package/@awesamarth/watchdog)\n[![license](https://img.shields.io/npm/l/%40awesamarth%2Fwatchdog)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-77c86f)](https://nodejs.org/)\n\nWatchdog gives you one live view of what your coding agents are doing, what they cost, how they relate to each other, and which controls the active harness can actually perform.\n\nIt works with the real Codex and Pi terminal interfaces. It does not replace either harness, put your agents in containers, or send their state to a hosted service.\n\n## Why Watchdog\n\nSubagents make parallel work possible, but they also make it easy to lose track of:\n\n- who spawned whom;\n- what each agent is currently reading, running, or saying;\n- which model and reasoning effort it actually received;\n- how many tokens and dollars the run is consuming;\n- whether work is duplicated, stalled, blocked, or looping;\n- and whether an agent, node, or execution can be safely stopped or retried.\n\nWatchdog normalizes those details across harnesses and exposes them through three local surfaces:\n\n- **Yard:** a live pixel-art overview of roots, subagents, loops, and graph stages.\n- **Operator:** exact topology, messages, tool activity, configuration, usage, warnings, graph edges, and controls.\n- **TUI:** a keyboard-first inspector and control surface for staying entirely in the terminal.\n\n## How Codex and GPT-5.6 were used\n\nWatchdog was designed, implemented, debugged, and validated through the Codex CLI with GPT-5.6, primarily GPT-5.6 Sol at extra-high reasoning effort. All product-development assistance came from Codex and GPT-5.6. Pi was used as a target harness for cross-harness integration rehearsals, not as a separate implementation assistant.\n\n- **Product shaping:** Codex helped turn an initial subagent-observability idea into a capability-aware control plane spanning subagents, loops, and execution graphs. It also challenged the boundary between Watchdog and existing harnesses so the project did not become another agent harness.\n- **Architecture:** GPT-5.6 designed the normalized event and capability contracts, per-run socket/registry model, Codex App Server integration, Pi extension and RPC-worker model, trace replay, and shared browser/TUI state.\n- **Implementation:** Codex worked across the TypeScript CLI/runtime, MCP integration, Pi extension, Ink TUI, React/Vite dashboard, pixel Yard, tests, package configuration, and user documentation.\n- **Integration research:** Codex inspected and exercised real Codex runtime surfaces to distinguish public capabilities from inferred behavior, including child topology, streamed activity, requested-versus-effective model configuration, token usage, and root/child control boundaries.\n- **Live validation:** Real Codex sessions spawned native children that Watchdog observed and interrupted. Real Pi sessions spawned persistent and nested workers, exercised steering, stopping, retry, model/thinking overrides, scoped delegation, and execution instrumentation.\n- **Bug discovery through dogfooding:** Watchdog was repeatedly developed through `watchdog codex`. Those runs exposed renderer corruption from terminal logging, unbounded control waits, incorrect nested-parent notification claims, opaque child assignments, requested/effective model mismatches, runaway Pi delegation, and worker-owned graphs hiding sibling agents. Each finding changed the implementation and received focused regression coverage.\n\nCodex therefore served both as the development collaborator and as one of the live systems under test. The resulting architecture, focused regression tests, and commit history preserve evidence of that process.\n\n## Supported harnesses\n\n| Harness | Integration | What Watchdog can do |\n| --- | --- | --- |\n| **Codex CLI** | Watchdog-owned Codex App Server plus a run-scoped MCP metadata tool | Observe roots and native children, stream messages and commands, compare requested/effective configuration, track tokens, instrument graphs, and use the controls Codex exposes |\n| **Pi** | Native Pi extension plus persistent Pi RPC workers | Add first-class subagents, nested delegation, messages/tools, tokens and provider cost, graph instrumentation, steer, follow-up, stop, retry, and model/thinking overrides |\n| **Ordinary Codex session** | Read-only persisted JSONL observer | Reconstruct near-live topology, tasks, activity, messages, configuration, and token usage without owning the process |\n| **Historical trace** | Streaming replay | Reopen completed runs in the same dashboard and TUI with every mutation control disabled |\n\nWatchdog is capability-aware. A button appears only when the selected harness and agent can truthfully perform that action.\n\n## Requirements\n\n- Node.js 22 or newer\n- Codex CLI and/or Pi already installed and authenticated\n- macOS or Linux for the local Unix-socket control plane\n\n## Install for Codex\n\nInstall the package globally:\n\n```bash\nnpm install -g @awesamarth/watchdog\n```\n\nFrom your real project directory, launch the normal Codex terminal UI through Watchdog:\n\n```bash\nwatchdog codex\n```\n\nWatchdog preserves your Codex authentication, configuration, working directory, tools, permissions, and terminal experience. It does not modify `~/.codex/config.toml`.\n\nNormal Codex arguments and prompts pass through unchanged:\n\n```bash\nwatchdog codex --model gpt-5.6-terra\nwatchdog codex \"Use two subagents to inspect this repository and report their findings.\"\n```\n\nOpen the browser dashboard from a second terminal:\n\n```bash\nwatchdog dashboard\n```\n\nOr stay in the terminal:\n\n```bash\nwatchdog tui\n```\n\n## Install for Pi\n\nInstall the same npm package as a Pi extension:\n\n```bash\npi install npm:@awesamarth/watchdog\npi\n```\n\nOrdinary future Pi sessions will load Watchdog automatically. The native footer reports the active worker count:\n\n```text\nwatchdog: active · 2/3 subagents\n```\n\nThe extension adds these commands:\n\n```text\n/watchdog-start    start or restart the local Watchdog runtime\n/watchdog-stop     stop Watchdog and its workers, not Pi\n/watchdog-status   show the run and worker counts\n/watchdog-agents   list workers and their current activity\n/watchdog-open     start or open the browser dashboard\n```\n\nIt also gives Pi a `subagent` tool for persistent workers and a `watchdog_execution` tool for loops and execution graphs. If another extension already owns `subagent`, Watchdog leaves it untouched and registers `watchdog_subagent` instead.\n\nPi users who also want the standalone `watchdog` CLI and TUI can install the package globally with npm. `watchdog pi` is an optional one-run convenience launcher; it never acts as a hidden installer.\n\n### Pi delegation safety\n\nNested delegation is default-deny. A worker receives the subagent tool only when its spawn request explicitly enables delegation. Child and depth budgets default to one, workers can control only their own subtree, and scoped instrumentation credentials never grant delegation rights.\n\nGlobal safety limits default to 12 workers, four concurrent model runs, and depth three. They can be adjusted when necessary:\n\n```bash\nWATCHDOG_PI_MAX_WORKERS=8 WATCHDOG_PI_MAX_CONCURRENT=3 pi\n```\n\n## Using the dashboard\n\n`watchdog dashboard` opens `http://127.0.0.1:4242` and reuses an existing Watchdog dashboard when one already owns that port.\n\n### Yard\n\nAn ordinary task renders honestly as `START → END`. Every direct subagent gets a labeled carriage on a perpendicular siding. Working cars remain out on their branches; completed cars return toward the main rail and older completed agents move into the Dock when the Yard becomes crowded.\n\nClick a train to inspect its assignment, transcript, commands, model and reasoning configuration, tokens, cost, and available controls. Click the German shepherd to pet him.\n\n### Operator\n\nOperator separates two structures that agent interfaces often blur together:\n\n- the **subagent topology**, which records who spawned whom;\n- the **execution graph**, which records stages, dependencies, branches, joins, subgraphs, verifiers, and loop-back edges.\n\nNode cards expose attempt history, correlated agent activity, traversed edges, evidence, budgets, warnings, and capability-derived controls.\n\n### Multiple sessions\n\nCodex and Pi runs remain independent even when they use the same project directory. Switch between them from the dashboard session picker or target a run explicitly:\n\n```bash\nwatchdog runs\nwatchdog tree --run <run-id-prefix>\nwatchdog tui --run <run-id-prefix>\n```\n\n## Using the terminal controls\n\nInspect a live run:\n\n```bash\nwatchdog ps\nwatchdog tree\nwatchdog inspect <agent-name>\nwatchdog tui\n```\n\nControl an agent when its adapter supports the action:\n\n```bash\nwatchdog steer <agent-name> \"Focus on the failing verifier.\"\nwatchdog follow-up <agent-name> \"Now check the edge case.\"\nwatchdog stop <agent-name>\nwatchdog retry <agent-name> --model <model> --effort low \"Retry with the retained evidence.\"\n```\n\nCurrent capability boundaries:\n\n| Target | Observe | Steer | Follow-up | Stop | Retry/model override |\n| --- | :---: | :---: | :---: | :---: | :---: |\n| Codex root | Yes | Yes | No | Yes | Yes |\n| Native Codex child | Yes | No | No | Yes | No |\n| Pi root | Yes | Yes | Yes | Yes | No |\n| Pi worker | Yes | Yes | Yes | Yes | Yes |\n| Observed/replayed run | Yes | No | No | No | No |\n\nThese are runtime capabilities, not promises Watchdog fakes around. For example, stopping a whole execution is offered only when every affected live agent is actually interruptible.\n\n## CLI reference\n\n### Launch, inspect, and navigate\n\n| Command | Purpose |\n| --- | --- |\n| `watchdog codex [args]` | Launch the normal Codex TUI with live Watchdog integration |\n| `watchdog pi [args]` | Launch Pi with Watchdog loaded for this invocation |\n| `watchdog dashboard [--port <port>]` | Start or reuse the local browser dashboard and open it |\n| `watchdog tui [--run <id>]` | Open the terminal inspector and control surface |\n| `watchdog doctor` | Diagnose Node, Codex/Pi availability, dashboard assets, and the current project runtime |\n| `watchdog runs` | List reachable live and replay runs for the current project |\n| `watchdog ps [--run <id>]` | Show a compact agent/process list |\n| `watchdog tree [--run <id>]` | Print the recursive subagent topology |\n| `watchdog inspect <agent> [--run <id>]` | Print the normalized state for one agent |\n| `watchdog observe [--once] [--session <id>]` | Follow or reconstruct an ordinary Codex JSONL session read-only |\n| `watchdog traces [--all]` | List saved Watchdog traces |\n| `watchdog replay [latest\\|trace.jsonl]` | Stream a saved trace back into the read-only dashboard/TUI model |\n\n### Agent controls\n\n| Command | Purpose |\n| --- | --- |\n| `watchdog steer <agent> <message> [--run <id>]` | Add guidance to an active steerable turn |\n| `watchdog follow-up <agent> <message> [--run <id>]` | Queue or start a context-preserving follow-up |\n| `watchdog stop <agent> [--run <id>]` | Interrupt an agent when its harness permits it |\n| `watchdog retry <agent> [--model <model>] [--effort <effort>] <message>` | Retry from retained context with optional supported overrides |\n\n### Loops and execution graphs\n\n| Command | Purpose |\n| --- | --- |\n| `watchdog loop set <agent> [options]` | Attach compatibility-loop policy to an agent or existing execution |\n| `watchdog loop evidence <agent> <summary>` | Record evidence for the current iteration |\n| `watchdog loop verify <agent> <pass\\|fail> [summary]` | Record the verifier result |\n| `watchdog execution declare <graph.json>` | Declare a named graph definition and run |\n| `watchdog execution update <execution> <patch.json>` | Update execution policy or metadata |\n| `watchdog execution start <execution> <node> [options]` | Start a concrete node attempt |\n| `watchdog execution finish-node <execution> <node> <activation> <pass\\|fail\\|stop>` | Finish one node attempt honestly |\n| `watchdog execution edge <execution> <edge> [options]` | Record a selected edge traversal |\n| `watchdog execution evidence <execution> <summary> [options]` | Attach evidence to an execution or node |\n| `watchdog execution verify <execution> <pass\\|fail> [summary]` | Record execution verification |\n| `watchdog execution stop <execution> [--node <node>] [reason]` | Stop a controllable node, subgraph, or execution |\n| `watchdog execution retry-node <execution> <node> [options] <message>` | Retry one retained, retry-capable node context |\n| `watchdog execution finish <execution> <complete\\|fail\\|stop\\|block>` | Finish the execution with an explicit outcome |\n\nRun `watchdog --help` for every option. Commands that target a registered run accept `--run <id-or-unique-prefix>` as shown in the built-in help.\n\n## Loops and execution graphs\n\nWatchdog does not assume that every task is a loop.\n\nWhen Codex or Pi calls `watchdog_execution`, the Yard uses the declared node names as stations and Operator shows the exact directed edges. A loop is a graph containing a traversed loop-back edge. A subgraph station opens its nested execution with a breadcrumb back to the parent Yard.\n\nInstrumentation can record:\n\n- named nodes and typed edges;\n- concurrent node attempts and assigned agents;\n- iterations and loop-back traversals;\n- verifier policy and results;\n- evidence and token/iteration budgets;\n- nested executions;\n- completed, failed, stopped, blocked, or incomplete outcomes.\n\nWithout authoritative instrumentation, Watchdog keeps the task opaque instead of guessing hidden stages.\n\nFor scripts and custom orchestrators, the CLI exposes the same execution model:\n\n```bash\nwatchdog execution declare ./workflow.json\nwatchdog execution start release-checks audit --agent root --iteration 1\nwatchdog execution edge release-checks audit-to-test --iteration 1\nwatchdog execution evidence release-checks \"Audit independently confirmed\" --node audit\nwatchdog execution verify release-checks pass \"Exit criterion satisfied\"\nwatchdog execution finish release-checks complete\n```\n\nRun `watchdog --help` for the complete execution and compatibility-loop command reference.\n\n## Observe an existing Codex session\n\nIf Codex was not launched through Watchdog, follow its persisted session JSONL in read-only mode:\n\n```bash\nwatchdog observe\nwatchdog dashboard\n```\n\nThe observer hydrates a bounded recent tail and then follows new records every 500 ms. It can reconstruct persisted topology, tasks, activity, messages, model/effort context, and token usage, but it cannot steer or interrupt the external process.\n\nUse `watchdog observe --once` to reconstruct the latest matching session and exit.\n\n## Reopen a completed run\n\nEvery owned or observed run writes an append-only trace under `.watchdog/runs/`.\n\n```bash\nwatchdog traces\nwatchdog replay latest\n```\n\nWhile replay remains active, open `watchdog dashboard` or target the printed run ID with `watchdog tui --run <id>`. Replay streams from disk, preserves the recorded topology and execution state, and remains strictly read-only.\n\n## Local-first by design\n\n- Runtime state remains in memory.\n- Controls travel over private per-run Unix sockets under `/tmp/watchdog-<uid>/`.\n- Active-run registrations live under `~/.watchdog/registry/`.\n- Append-only traces live inside the current project at `.watchdog/runs/`.\n- The dashboard binds to `127.0.0.1` by default.\n- Watchdog does not require an account, hosted backend, or telemetry service.\n\nYour harness provider still receives whatever the underlying Codex or Pi session normally sends to it. Watchdog does not add a separate cloud data path.\n\n## Develop locally\n\nThis section is for contributors. Users installing from npm do not need Bun or the source checkout.\n\n```bash\ngit clone https://github.com/awesamarth/watchdog.git\ncd watchdog\nbun install\nbun run dev -- codex\n```\n\nLaunch other development surfaces:\n\n```bash\nbun run dev -- pi\nbun run dashboard\nbun run dev -- tui\n```\n\nLoad the source extension directly into Pi:\n\n```bash\npi --extension ./src/pi/extension.ts\n```\n\nOr build and install the checkout into future Pi sessions:\n\n```bash\nbun run build\npi install .\n```\n\nUse `pi install . -l` for a project-local extension installation.\n\n### Verify a change\n\n```bash\nbun run check\nbun run test\nbun run test:web\nbun run build\nbun pm pack --dry-run\n```\n\nPublished output targets ordinary Node.js 22 and must not depend on Bun at runtime.\n\n## Contributing\n\nBug reports, focused feature proposals, and pull requests are welcome through [GitHub Issues](https://github.com/awesamarth/watchdog/issues). Please preserve adapter capability boundaries: never expose a control the underlying harness cannot truthfully perform.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}