Watchdog

Control subagents, agentic loops, and execution graphs from one local command centre

Comment

Inspiration

Subagents, agentic loops, and execution graphs are fairly new, powerful ways to tackle complex tasks. However, I noticed that users are currently unhappy with them as they become harder to understand and control as they grow.

Users cannot easily inspect what subagents are doing, intervene when they go off course, or understand why an orchestration is consuming so many tokens. Sometimes subagents requested with cheaper models and lower reasoning effort are launched with more expensive configurations instead. Combined with branching graphs, retries, and loops, these problems become even more pronounced.

The good thing is that these capabilities also create a new design space for developer tooling. Watchdog came from the idea that users should not have to surrender control just because their agents are becoming more autonomous.

What it does

Watchdog is a local-first operator control plane for subagents, agentic loops, and execution graphs.

It shows root agents and subagents alongside their assignments, responses, tool activity, token usage, status, and requested versus effective model configuration. Execution graphs expose branches, joins, nested subgraphs, verifiers, iterations, evidence, budgets, warnings, and loop-back edges.

Users can stop, steer, follow up, or retry agents wherever the connected harness supports those actions.

Watchdog has three interfaces:

  • The Yard, a pixel-art dashboard where agents become trains moving through an execution
  • Operator, a detailed debugging view for graphs, activity, evidence, warnings, and controls
  • A TUI and CLI for terminal-first workflows

It currently supports Codex CLI and Pi. Traces stay on the user's machine and completed sessions can be reopened in read-only replay mode.

How I built it

I first used Codex to inspect its own installed package, App Server protocol, persisted JSONL traces, and available control surfaces. This helped establish what Watchdog could implement truthfully and which capabilities Codex does not expose.

Watchdog connects to the Codex App Server, normalizes live runtime events, and provides a run-scoped MCP surface for declaring execution graphs.

For Pi, Watchdog uses Pi's extension system and RPC mode. Its extension includes graph instrumentation and a bounded subagent runtime because Pi is a minimal harness which intentionally does not ship with a native subagent primitive.

Both integrations feed the same harness-independent runtime model, so the dashboard and TUI do not need to understand Codex or Pi internals.

The project is written in TypeScript using Bun for development, React and Vite for the dashboard, React Ink for the TUI, and Playwright for browser testing. The published package runs on Node.js 22.

I built Watchdog almost entirely with Codex using GPT-5.6 Sol at xhigh reasoning. Codex helped investigate runtime behaviour, design the architecture, implement both integrations, debug real multi-agent sessions, build the interfaces, and package the product. I focused on shaping the product, challenging assumptions, and testing whether the controls worked in real sessions.

Challenges I ran into

The Codex integration required the most investigation. Its App Server, remote CLI, native subagent tools, and JSONL traces expose different pieces of the runtime. Some approaches worked in isolation but failed during real interactive sessions. Printing Watchdog events after the native Codex TUI started, for example, corrupted its terminal renderer.

Codex subagents also have strict capability boundaries. Native children can be interrupted, but cannot always be steered or retried directly. Requested model and reasoning configurations may also differ from what is actually used. Watchdog had to represent these limitations honestly.

Pi created a different problem. An early implementation allowed every worker to inherit delegation, causing one audit to unexpectedly expand into eleven workers. I redesigned it around scoped credentials, explicit delegation permission, concurrency limits, and child-depth budgets.

The visual dashboard also required careful state management. Worker-owned graphs could hide the root Yard, completed executions could remain marked as running, and newly connected sessions could leave stale UI state. Solving these issues required separating agent topology, graph ownership, navigation, and execution lifecycle.

Accomplishments that I'm proud of

I am proud that Watchdog works across two very different agent harnesses without reducing either one to a lowest-common-denominator interface.

I am especially proud of the Yard. It turns a difficult observability problem into a fun interface with personality: the root becomes an engine, subagents become carriages, graph nodes become stations, and a German shepherd watches over the system. Underneath that playful interface is a serious debugging and control surface.

Watchdog now includes capability-aware controls, nested execution graphs, loop and verifier state, orchestration warnings, local trace replay, and a single npm package containing both the CLI and Pi extension.

What I learned

I learned that subagent topology and execution graphs are related, but not interchangeable. A tree explains who spawned whom, while a graph explains how work, dependencies, branches, verification, and retries flow through the system. Loops are cycles inside that graph.

Most importantly, I learned how much demand exists for tooling around agent harnesses. As agents gain more autonomy, developers will need better ways to inspect, constrain, debug, and understand them.

What's next for Watchdog

Next, I want to explore Claude Code, OpenCode, and other extensible agent harnesses.

I also plan to improve automatic loop and verifier capture, strengthen Codex cost reporting, refine the product through user feedback, and improve installation and distribution.

The long-term goal is for Watchdog to become a common local control surface for complex agent execution, regardless of the harness running underneath it.

Built With

Share this project:

Updates