> ## Documentation Index > Fetch the complete documentation index at: https://smithers.sh/llms.txt > Use this file to discover all available pages before exploring further. # Workflow supervisor > Live outline of workflow phases and agents; the right pane of the herdr cockpit (also runnable in a bare TTY). # 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ` | Attach that gateway; **hard-fails** if it is unreachable (you pinned it) | | `--gateway auto` | Explicitly start-or-attach (honored even headless) | | `--db ` | 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 ` 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 | ## Related * Herdr host guide: `docs/integrations/herdr.mdx` * Fixture campaign: `scripts/top-outline-campaign.mjs`