Workflow supervisor

The workflow supervisor is the live outline of phases and agents for what Smithers is running. In the herdr cockpit it is the right pane (human harness on the left). The same process also works in a bare TTY.

smithers supervisor                          # default: gateway auto (interactive), falls back to direct-db
smithers supervisor --gateway http://host:7331  # attach a specific gateway (hard-fails if unreachable)
smithers supervisor --direct                 # force direct smithers.db reads (bypass the gateway)
smithers supervisor --db /path/to/smithers.db   # read exactly this db (implies direct reads)
smithers supervisor --cwd /project
smithers supervisor --interval 0.5

(smithers top is a hidden compatibility alias for the same command; prefer smithers supervisor.)

Data source (gateway vs direct)

The supervisor reads through the workspace gateway by default. With no flag it resolves --gateway auto: it starts-or-attaches the workspace gateway and sources fleet, focus, outline, and per-node activity over it. If no gateway is reachable, the default path silently falls back to direct smithers.db reads (a warning to stderr); it never hard-fails, and it needs no local smithers.db when a gateway answers.

Flag	Behavior
(none), interactive	`--gateway auto`: start-or-attach the workspace gateway; fall back to direct-db if none is reachable
(none), headless / piped	Direct `smithers.db` reads; the default only autostarts a gateway daemon in a TTY, so `timeout N smithers top` and other scripted uses stay instant and leave no daemon behind
`--gateway <url>`	Attach that gateway; hard-fails if it is unreachable (you pinned it)
`--gateway auto`	Explicitly start-or-attach (honored even headless)
`--db <path>`	Read exactly that database. A pinned db implies direct reads; the gateway serves its own workspace db, not an arbitrary path. Combining `--db` with an explicit `--gateway <url\|auto>` keeps the gateway for primary reads (a stderr note says so) and `--db` only backs the local detail panes
`--direct`	Force direct `smithers.db` reads, bypassing the gateway; the escape hatch for diagnosing a broken gateway

The title bar shows a small via gateway / direct tag next to LIVE/IDLE so you always know which read path is answering. On the gateway path, per-node tool activity is fed by a resilient StreamRunEvents subscription; a stream drop degrades the activity strip to its last-known lines (never crashing the TUI), and reconnects on its own. --gateway/--direct and --cwd resolve consistently: --cwd selects the workspace for gateway discovery just as it does for direct-db discovery.

Host	How
Herdr cockpit	Right pane of the harness‖supervisor tab
Bare terminal / SSH / tmux	Same argv in any TTY
CI / pipe	Prefer machine APIs; supervisor is interactive

What it is / is not

Is	Is not
Live workflow tree (phases, agents, status, model)	A herdr layout engine
Store-scoped (`--db` / discover from cwd)	Bound to one run id forever
Entry point for Enter → detail tab (inspect / steer)	The agent harness UI
Deterministic digest (tallies / active / attention)	An LLM summary of the run

Regions (top → bottom)

Region	Content
Title	LIVE/IDLE · `via gateway`/`direct` data-path tag · Workflow Supervisor · SMITHERS
Run strip	workflow · run id · status · elapsed
Digest	Deterministic tallies: working / blocked / failed / done; active nodes; attention; queued steers
Outline	Phase/agent tree (graph-primary when frames exist)
Activity	Selected agent’s recent tools/actions (direct-db events, or streamed `StreamRunEvents` on the gateway path)
Footer	Keys / status toasts

Multi-run stores: switch focus with [ / ] / f; no fleet strip in the supervisor. Digest is pure store math (same builders as tail --overview). It is not an agent-written narrative; put those in the harness if you want LLM heartbeats.

Terminology

Term	Meaning
cockpit	Herdr tab that hosts harness (left) + workflow supervisor (right)
workflow supervisor	This outline TUI (`smithers supervisor`)
detail tab	Per-node stream + dual-control dock (`tail --node --hud --linger`)

Keys

Key	Action
`j` / `k`	Move selection
`Enter`	Open herdr detail tab (or print inspect command)
`[` / `]`	Previous / next run
`f`	Follow live run
`g` / `G`	Top / end of tree
Mouse wheel	Scroll view only (when content overflows)
Click	Select row
`q`	Quit

Herdr host guide: docs/integrations/herdr.mdx
Fixture campaign: scripts/top-outline-campaign.mjs

Start here

Tutorials

Set up

How-to guides

Reference

Explanation

Compare

Workflow supervisor

Workflow supervisor

Data source (gateway vs direct)

What it is / is not

Regions (top → bottom)

Terminology

Keys

​Workflow supervisor

​Data source (gateway vs direct)

​What it is / is not

​Regions (top → bottom)

​Terminology

​Keys

​Related

Workflow supervisor

Data source (gateway vs direct)

What it is / is not

Regions (top → bottom)

Terminology

Keys

Related