Agent Watchboard

Desktop watchboard for orchestrating multiple code agents across persistent terminal workspaces, shared task boards, and reconnectable runtime panes.

Overview

Agent Watchboard is a desktop control surface for people who run more than one coding agent at the same time and need the runtime state to stay visible.

It combines three layers in one application:

• persistent workspace templates for Codex, Claude Code, bash, and custom terminal profiles
• a split-pane runtime workbench with reconnectable PTY sessions
• a shared Todo Board that stays in sync with the repo-local todo_preview CLI and skill

The current real-world target is Windows with WSL, where host-side and WSL-side tools need to coexist without forcing the user to mentally switch between two different environments.

Platform Support

• Windows
• Windows + WSL
• Linux

Windows + WSL is the setup that has been exercised most heavily in day-to-day usage.

Supported Agents

• Codex
• Claude Code
• plain shell / bash profiles
• custom terminal profiles built from saved workspace templates

Why This Exists

Typical agent tooling still treats each terminal as an isolated session. That breaks down when you want to:

• keep multiple agents open across different repos and environments
• reconnect after closing the UI
• switch between host and WSL paths without losing context
• track shared tasks in a board that both the desktop UI and CLI can mutate
• understand which agent is ready, working, stalled, or stopped

Agent Watchboard is designed as the missing operational layer above individual agent CLIs.

Core Capabilities

• Save workspace templates and launch them into tabs, splits, or background runtime instances.
• Reconnect to live PTY sessions after restarting the desktop UI instead of discarding terminal state.
• Run host and WSL workspaces side by side in a single watchboard.
• Inspect skills, configs, and runtime state from the same application shell.
• Share a JSON Todo Board between the desktop app and terminal automation through todo_preview.
• Persist workbench layout, workspace definitions, settings, and runtime diagnostics outside the repository.

Development Priorities

These are the two product directions the project is being shaped around:

1. Seamless Multi-Environment Operation

The long-term goal is to make agent execution feel continuous across:

• host
• WSL
• server / remote runtime targets

Today the app already supports host and WSL workflows. The next step is to extend the same visual language, runtime health model, and path-aware tooling into remote or server-backed agent environments without forcing separate UIs.

2. Multi-Agent Monitoring And Sync

The watchboard is meant to become a single surface for supervising several agents at once:

• unified session state and health visibility
• synchronized task tracking through the board + CLI bridge
• consistent workspace identity across Codex and Claude Code
• better operational insight into which agent is running, idle, blocked, or producing output

Quick Start

pnpm install
pnpm dev

Build

pnpm build
pnpm dist:linux
pnpm dist:win
pnpm dist:win:portable

Notes:

• Linux packages are written under release/ as AppImage.
• pnpm dist:win writes a runnable release/win-unpacked/ folder that is useful for Windows-side testing from a non-Windows host.
• On WSL/Linux hosts, pnpm dist:win intentionally skips native dependency rebuild and Windows executable resource edits. This keeps node-pty on its bundled Windows prebuilds and avoids requiring wine for the unpacked test bundle.
• pnpm dist:win:portable produces a Windows portable .exe when the host environment has the required Windows packaging tooling such as wine.

CLI

pnpm todo_preview list
pnpm todo_preview add "new task" --topic Inbox
pnpm watchboard --help

Headless E2E Contract

End-to-end tests in this repository are expected to run without a graphical desktop session.

• Electron Playwright suites should launch the app through tests/e2e/headlessElectronApp.ts.
• The shared helper applies the repository-standard headless contract:
  • WATCHBOARD_HEADLESS_TEST=1
  • WATCHBOARD_DISABLE_GPU=1
  • Chromium flags that disable GPU- and display-dependent rendering paths
• The main process must keep test windows offscreen and must not surface a desktop-visible BrowserWindow.
• New E2E suites should not call _electron.launch(...) directly unless they preserve the same contract.

Stable invocation patterns:

• Inside this repository: pnpm todo_preview ...
• Outside this repository: pnpm --dir /home/sdu/pure_auto/agent_watchboard todo_preview ...
• In restricted/sandboxed runtimes where tsx may fail: node /home/sdu/pure_auto/agent_watchboard/dist-node/cli/todo-preview.cjs ...

E2E gating note:

• pnpm test:e2e is intentionally blocked on local machines so it does not accidentally start Electron E2E on a developer desktop.
• CI runs the gated suite through pnpm test:e2e:ci, which requires CI=1 or CI=true.

todo_preview Skill Setup

todo_preview is the shared task-management surface for this project. The desktop board UI and the CLI both read and write the same JSON board file, so agents can update tasks from the terminal while the app reflects the changes immediately.

If you want your agent runtime to invoke the skill directly, expose this repository skill in the agent's skill search path:

• Codex: make sure skills/todo_preview/SKILL.md is visible from your Codex skills directory, usually by copying or symlinking this repository skills/ folder into ~/.codex/skills/.
• Claude: expose the same repository skills/ folder in the Claude-side skill location you use for local skills.
• Repository-local fallback: even without global skill installation, you can always run the CLI directly with pnpm todo_preview ... from this repository.

The default board path is ~/.agent-watchboard/board.json. Keep the desktop app and CLI pointed at the same file if you want one shared board view. Override the path when needed:

pnpm todo_preview --file ~/.agent-watchboard/board.json list

If you are not currently in the repository root, use:

pnpm --dir /home/sdu/pure_auto/agent_watchboard todo_preview --file ~/.agent-watchboard/board.json list

If your runtime blocks tsx child IPC features, use the built CLI directly after pnpm build:

node /home/sdu/pure_auto/agent_watchboard/dist-node/cli/todo-preview.cjs --file ~/.agent-watchboard/board.json list

Common todo_preview Workflows

List the current board:

pnpm todo_preview list

Add a task into a topic:

pnpm todo_preview add "Investigate CI failure" --topic Inbox

Add a task with more detail and a deadline:

pnpm todo_preview add "Release v0.5.2" --topic Release --description "Push tag after CI passes" --ddl 2026-03-13

Mark a task as in progress or done:

pnpm todo_preview doing "Investigate CI failure"
pnpm todo_preview done "Investigate CI failure"

Move a finished task back to todo:

pnpm todo_preview todo "Investigate CI failure"

Rename a task and update metadata:

pnpm todo_preview update "Release v0.5.2" "Publish v0.5.2" --description "Close release issue after green CI" --ddl 2026-03-13

Set or clear a deadline:

pnpm todo_preview ddl "Publish v0.5.2" 2026-03-14
pnpm todo_preview ddl "Publish v0.5.2" --clear

Move a task into another topic:

pnpm todo_preview move "Publish v0.5.2" Release

Rename or reorganize topics:

pnpm todo_preview rename-topic Inbox Triage

Remove an obsolete task or section:

pnpm todo_preview remove "Old follow-up"

Import an older Markdown checklist one time into the JSON board:

pnpm todo_preview migrate-markdown ./legacy-todo.md

Apply several mutations atomically from one JSON file:

pnpm todo_preview batch ./ops.json

Example ops.json:

[
  { "op": "add", "topic": "Circuit", "name": "SRAM data analysis" },
  { "op": "add", "topic": "Circuit", "name": "Compute unit analysis" },
  { "op": "ddl", "name": "SRAM data analysis", "date": "2026-03-20" }
]

Runtime Data And Logs

The app persists runtime data outside the repository:

• Windows: %APPDATA%/agent-watchboard/
• Linux: ~/.config/agent-watchboard/

Shared todo board default path:

• Host / Linux: ~/.agent-watchboard/board.json
• Windows app default: WSL-side ~/.agent-watchboard/board.json

Important runtime files:

• workspaces.json
• workbench.json
• settings.json
• supervisor-state.json
• logs/main.log
• logs/supervisor.log
• logs/sessions/<workspaceId>/<terminalId>.log