--- title: Agent Status Board --- # Agent Status Board ## What it is A live board inside Omniscio that shows, for every Claude Code session Omniscio has launched: where that agent is working, what state it's in, where it sits in its dev-pipeline, and its **to-do list** — with one-click jump to the session. ### What you see There are **three surfaces**, all showing the same per-agent data: 1. **Global board** — click the **Agent Board** icon (a dashboard glyph) in the top-right toolbar. A full-screen list opens with one card per live agent. Click any card to jump straight to that session's chat. (The icon lives in the toolbar's overflow menu by default; you can pin it like any other toolbar item.) 2. **Per-session section** — at the top of any session's panel, a collapsible **"Agent Board"** section shows that one agent's full checklist + pipeline state. It only appears for sessions that actually have board data (a real spawned agent); it stays hidden for virtual projects, sessions started before the feature existed, or when the feature is off. 3. **Dev Pipeline panel tab** — if you use the Dev Pipeline panel, its left rail has an **"Agent Board"** tab that shows the very same full board right inside the panel. It appears only when this feature is on, and it's the same board as the toolbar icon — just a second way in. The same record also feeds a crew's **Dashboard** in the Overseers hub: each active crew member's row shows how far through its checklist it is ("3 of 7 steps · Now: …"), and clicking that line opens the full checklist in place. A member whose card says **No to-do tool** or **Skipped the to-do rule** shows that same label on its row. All of it is read from this board's own data, never copied, so it too appears only while this feature is on. See [agent-crews.md](agent-crews.md). Each card shows: - a **status** chip (Running / Needs You / Error / etc.), - the **project** name and the **workspace / worktree** path the agent is in, - the **dev-pipeline phase** (shown with a friendly label like "Build", not `PHASE_3_BUILD`) and current **gate**, if the agent's workspace is running the dev-pipeline, - clickable **doc links** to the run's standardized dev-pipeline documents — **Plan**, **Acceptance**, **Red Team**, **Elegance**, **Contract** — shown beside the phase/gate. Clicking one opens that document in Omniscio's built-in preview pane. Each link appears once its document has been written (they accrue as the run advances) and **keeps working after the run finishes** — Omniscio snapshots each doc into its own store, so a link survives the run's `.claude/pipeline/` scratch folder (and even the whole worktree) being cleaned up, - a **"Waiting at gate"** badge when the agent is parked awaiting a gate, - a **"No to-do tool"** tag when that agent's Claude Code started it without the to-do tool (so an empty list there means "can't keep one", not "nothing to do"), and a **"Skipped the to-do rule"** tag when the to-do rule let it through after refusing it twice — hover either for the reason, - **what the agent is doing right now** — when a running agent is inside a tool call, the card shows that tool and how long it has been in it (e.g. `Bash 40m`). This is the difference between "quietly working" and "frozen": an agent produces no output at all between starting a command and getting its result, so a long build or a queued test run used to look identical to a hang. With several tools running at once it shows the one it has been waiting on longest — the one actually holding things up. The chip appears only while the agent is genuinely running, and its timer counts up from when the call started, so a stale card visibly ages instead of quietly reassuring you, - the agent's **to-do list** — a one-line `done / total` summary plus the current in-progress item on the global board (with a **"Show details"** toggle that opens the full checklist there too); the full checklist always shown in the per-session section. Each item has a **color-coded status marker** — a green check (done), an accent dot (the task being worked on now), or a faint circle (to-do) — and the **in-progress task is emphasized** (bold) so it's easy to spot. A task with a longer **description** shows it inline for the active task (for context) and tucked behind a small toggle on the rest — **tap to reveal** the full text, - when it was **last updated**. On the global board, agents that have sat **idle for 6+ hours** and aren't in an attention state (running / needs-you / error / stalled) are collapsed behind a **"Show N idle agents"** toggle, so the live agents aren't buried. They're never dropped — one click reveals them. The board is **view-only** — there are no buttons to approve gates or drive the agent from it. "Waiting at gate" is shown for awareness; you act by jumping into the session. ## Where to find it ### Turning it on or off The board is **off by default** — it's opt-in. To turn it on: **Settings → Workflow → "Agent Status Board"**. While off (the default), Omniscio saves nothing, the board stays empty, and the toolbar icon is hidden; switching it on brings back the saved cards and fills in every live agent within a few seconds. There is also a **hard kill switch** for debugging without touching settings: launch with **`AMC_DISABLE_AGENT_STATUS_BOARD=1`**, which forces the board off even when the setting is on. (The older `AMC_DISABLE_BOARD_OBSERVE_GATE` switch is gone — there is no 30-second refresh left for it to restore.) Turning the board on also turns on the **to-do rule** (below); a developer can switch the rule off alone with **`AMC_DISABLE_TODO_GATE=1`**, which lets every edit through without asking. Separately, and whether the board is on or not, Omniscio switches Claude Code's to-do tools on for every agent it launches; **`AMC_DISABLE_CLI_TODO_TOOLS=1`** stops that. ## How it behaves ### How it's captured (and why it's reliable) **Omniscio builds the whole board itself — nothing the board shows depends on a hook in your agents.** (The one hook it adds, while the board is on, is the to-do rule below — it only decides whether an edit may go ahead.) Whenever something happens to an agent — it updates its to-do list, finishes a turn, or changes status — Omniscio rebuilds that agent's card from sources it can already reach: - **status, phase, gate, doc links** — from the session row plus the run's `.claude/pipeline/state.md` (read-only; Omniscio never writes a run's state, and renames a leftover copy only to retire it) — in the agent's worktree, or, for a run that has not reached Build yet, in its private run folder `~/.claude/dev-pipeline-runs//`. When a worktree and a private run folder both hold a state file for the same run, the one written last wins — and if that one is retired, the card shows no phase at all. Each doc is resolved inside the folder the run was found in, then **copied into Omniscio's own store** (an `agent-status/artifacts//` folder inside Omniscio's data folder) the first time it's seen — so the link keeps working after the source doc is deleted (re-copied only when the doc actually changes), and the copies go when the agent's card leaves the board. - **what it's doing right now** — from Omniscio's own reading of the agent's output stream. Every tool call an agent starts is noted when it begins and cleared when its result comes back, so the board knows which call is still open and since when. This lives only in memory and is never saved to disk: a command cannot outlive the process running it, so after a restart the board correctly shows nothing rather than resurrecting a call that ended hours ago. - **to-do list** — mirrored from the harness's own per-session task store at `~/.claude/tasks//`, the same files Claude's `TaskCreate`/`TaskUpdate` tools (and superpowers, which use them) write. So the checklist shows up no matter which to-do system the agent uses. Each task's longer **description** rides along as the item's detail (collapsed to one line, length-capped, and skipped when it just repeats the title), which is what the expandable detail shows. Claude changes an agent's internal session id when it restarts or auto-compacts, and the saved checklist stays under the _original_ id — so Omniscio remembers **every** id an agent has used and reads the list from whichever one actually holds it, instead of just the latest. Each card is saved as **one row in Omniscio's own database**, keyed by the Omniscio session id, and only when something on it actually changed; then the UI is told to refresh. Because Omniscio is the only writer, nothing depends on the agent choosing to report anything. Finished/idle sessions (`ended`, `ready`) drop off the board, and so does a session that is archived or deleted — its card, its saved row and its document copies all go, even when nothing announced the change. **After a restart the board is there straight away.** The saved cards are loaded when Omniscio starts (or the moment you open the board, if that comes first), so you never stare at an empty board waiting for each agent to do something. **It never sweeps in the background.** There is no timer walking every agent: a card is rebuilt only when its agent does something, and several things happening at once are folded into one quick refresh. The only repeating work is a light check — at most once a minute, and only while a board is on screen — that catches anything no event announced, such as an archive. With nothing happening and no board open, the board does **nothing at all**. ### The to-do rule — agents keep the list the board shows A board of empty checklists tells you nothing, and left alone most agents never wrote a list — about one in five that edited files did. So **while the board is on, Omniscio holds every agent it launches to keeping one**: - **Agents are told up front.** Every session the rule applies to starts with a one-line **TO-DO LIST** instruction in Omniscio's built-in instructions: plan with the to-do tool before editing, and keep the list current. So an agent does not have to learn the rule from a refused edit. A session the rule does not apply to — a reviewer, Clean Room, a remote (SSH) session, another AI engine — never gets the line. - **No file edits before a list.** An agent's first attempt to edit or create a file is refused until its to-do list has at least one item. The refusal tells it to write its plan as a list and hands it a seven-step standard to fill in — restate the ask, look before changing anything, plan, do the work, check it works and capture the proof, update any affected docs, report back with the evidence. An agent running the dev pipeline is pointed at its six stock phase items instead. - **A pipeline phase closes with its checklist.** A dev-pipeline run can't move itself to its next phase while the phase it is leaving still has unticked items in its checklist, or its own phase to-do item isn't marked done. The refusal names every open item; ticking them off — or deferring one with a reason — lets it through. - **It never gets an agent stuck.** The edit goes through whenever Omniscio can't answer, after two refusals, for sub-agents, and for any agent that started without a to-do tool. Only the agent's own session is judged, and only the edited file's path is sent — except a pipeline state-file edit, which the phase check has to read. An agent let through after two refusals shows **"Skipped the to-do rule"** on its card. - **A phase moved around the rule is still caught.** The rule only sees edits made with the editing tools, so a run could change its phase with a shell command instead. If it does while the phase it left still has open items, Omniscio sends it **one** follow-up at the end of that turn naming them — never twice for the same phase, and not at all for a move the rule already refused. **You hear about a Claude Code version that drops the to-do tool.** If agents on some Claude Code version start without the to-do tool, you get **one inbox card for that version** (not one per agent), with a button that starts an agent to find out why and fix it. The card clears itself once an agent on that version starts with the tool again. **Claude Code's to-do tools are switched back on.** Claude Code 2.1.280 stopped offering its to-do tools to newer models unless a setting is on, so from late September agents on those models kept no list at all and their checklists went blank — with no error anywhere. Omniscio now turns that setting on for every agent it launches — on this computer, over SSH and on a cloud machine — unless a developer or a remote profile has set it already. Remote agents — over SSH or on a cloud machine — get the tools but not the to-do rule, which applies to agents running on this computer. ### Troubleshooting - **A session shows no "Agent Board" section** — that session has no board entry. Expected for virtual projects (Gmail, Tasks, etc.), sessions started before the feature shipped, or when the feature is off. - **The to-do list is empty for an agent** — that agent hasn't created any tasks (via Claude's task tools). It will still show its status and, if it's running the dev-pipeline, its phase/gate — just no checklist. With the board on, an agent must write a list before it edits a file, so an empty list usually means it hasn't edited anything yet, or it's a remote agent (the to-do rule applies only on this computer). - **An agent says its edit was refused until it writes a to-do list** — that's the to-do rule doing its job: the agent writes its list and carries on. It refuses an agent at most twice for a missing list (and at most twice per phase change), then lets the edit through. A developer can switch it off with `AMC_DISABLE_TODO_GATE=1`. - **A paused, long-running, or restarted agent keeps its checklist** — Omniscio tracks every internal session id an agent has used and shows the to-do list from whichever one currently holds it, so the checklist survives the id changes that auto-compaction and restarts cause. The checklist clears only if the agent itself empties its task list, and the whole row drops when the session ends. (Older builds looked under a single id that Omniscio overwrote on each restart, so paused/restarted agents often showed a blank checklist while the list sat under their original id — that's fixed. Note: a few very old agents whose id history had already scrolled out of the logs before this shipped can't be recovered retroactively.) - **Phase / gate is blank** — the agent isn't running the dev-pipeline (those fields come from reading the run's `.claude/pipeline/state.md`, in its worktree or its private run folder). Omniscio never writes a run's state: it only reads it, and the one write it does make is to RENAME a leftover copy out of the way when both homes hold one (see the next entry). - **A card shows an old phase for a run that already finished** — the run wrote `## Status: complete` in its worktree, but the pre-Build copy it left in its private run folder still read `active` and used to win. Both are now fixed: the file written last wins, and a newest copy that is retired shows nothing. The refresh also renames a provably older leftover to `state.md.superseded`, so a run folder and a worktree stop disagreeing in the first place. A leftover whose worktree was already deleted before that happened is the one case that cannot be untangled. - **No doc links on a card** — same root cause (not running the dev-pipeline), or those documents haven't been written yet (a link shows only once its file exists, and only for documents inside the agent's own workspace). - **The board says it couldn't load, with a Retry button** — the board's data fetch failed. Click **Retry**; it re-runs the fetch, and the button pauses briefly between attempts so a repeated tap can't hammer a call that is still failing. The board also refreshes itself whenever an agent's status changes, so a passing failure usually clears on its own. If it keeps failing, check the Diagnostics tape (Settings → Diagnostics). Earlier builds showed a loading placeholder forever in this case, with no error and no way to retry. - **A card says "No to-do tool"** — that agent's Claude Code started it without the to-do tool, so it can't keep a list and the to-do rule doesn't apply to it. If a whole Claude Code version does this, the inbox card for that version is the place to start. - **A doc link didn't open** — older builds kept the board's copies somewhere the file viewer wasn't allowed to read, so the links silently did nothing; that's fixed, and every doc link opens in the preview pane. - **An agent I expected is hidden** — it may be collapsed under "Show N idle agents" (idle 6+ hours and not in an attention state). Click the toggle to reveal it. ## For agents ### For agents working in the code - Format, types, schema, merge and caps (import-safe in main AND renderer): `src/shared/agent-status-board.ts`. - Board service — the in-memory board, the start-up load of saved rows, the refresh flush, the reconcile, the read-time live-tool overlay and the change push: `src/main/services/agent-status-board-service.ts`. Saved rows: table `agent_board_entries`, via `src/main/db/queries-agent-board-entries.ts`. - Event-driven refresh: the coalescing queue `src/main/services/agent-board/board-refresh-queue.ts` and its triggers `board-triggers.ts` (a finished `TaskCreate`/`TaskUpdate`, `turnEnded`, `statusChanged`, the `SESSION_STATUS_CHANGED` push, the enabled flag). Harness task-store reader: `src/main/services/agent-board/task-store-cache.ts`. - Flags and follow-ups: `todo-rule-skips.ts` (what the rule let through), `todo-tool-inbox.ts` (the per-version inbox card), `phase-backstop.ts` + `phase-open-items.ts` (the end-of-turn follow-up, sharing the rule's open-items logic), all in `src/main/services/agent-board/`. Board folder: `board-dir.ts`, which the file viewer's allow-list reads too. - Renderer store: `src/renderer/src/stores/agent-status-board-store.ts` — `hydrate()` (the async `AGENT_STATUS_BOARD_GET` boot pull) + `hydrateFromBootstrap()` (the synchronous mobile first-paint seed). Views: `AgentBoardList.tsx` (the shared, layout-neutral list body — reused by BOTH the global view and the Dev Pipeline panel's "Agent Board" tab, so they can't drift), `AgentStatusBoardView.tsx` (global full-screen shell around the list), `AgentBoardCard.tsx` (row), `SessionAgentBoardSection.tsx` (per-session). De-clutter rule (pure): `board-partition.ts`. Doc-link opener: `open-board-artifact.ts`. - **Mobile first-paint seed (no scroll shove)** — the per-session strip is seeded from the `WEB_BOOTSTRAP` `agentBoard` field (`hydrateFromBootstrap`) so it is present BEFORE the scroll engine positions on mobile. Without it the async `hydrate()` GET resolved after the panel painted, mounting the strip late and shoving the message down ~30px. After that seed the board refreshes LIVE on mobile too — `AGENT_STATUS_BOARD_CHANGED` is in `INBOX_ALLOWED_CHANNELS`, so the push reaches web clients and the App-level `usePushListener` (debounced) refetches. Detail: [mobile-remote-access.md § Bootstrap agent-board seed](mobile-remote-access.md) + the contract's `the-live-push-reaches-mobile-too` / `the-per-session-strip-is-seeded-at-first-paint`. - **Event-driven refresh (`the-board-refreshes-on-events`)** — no periodic tick: a card refreshes when its agent does something, and the renderer's `useBoardObservation` ping (board-scope in `AgentBoardList`, session-scope in `SessionPanel`) only throttles in a reconcile (≤ 1/min, full board) or asks for a missing card (session strip). The old `AMC_DISABLE_BOARD_OBSERVE_GATE` switch is retired. See the contract's `the-board-refreshes-on-events` and `a-session-that-leaves-leaves-the-board`. - **The to-do rule** — decision `src/main/services/agent-board/todo-gate.ts` (on/off: `todo-rule-switch.ts`), route `POST /agent-board/todo-gate`, relay hook `resources/todo-gate/todo-gate.mjs`, spawn wiring `src/main/process/todo-gate-spawn.ts`. The to-do tools switch: `src/main/process/cli-todo-tools-env.ts`; whether each agent really started with a to-do tool: `src/main/process/todo-tool-availability.ts`. Contracts: the board contract's to-do rules and `.claude/memory/contracts/cli-todo-tools-on-contract.md`. - **Before changing it, read the feature contract**: `.claude/memory/contracts/agent-status-board-contract.md` — it names the invariants (one writer and one saved row per session `single-owner-one-row`, event-driven refresh `the-board-refreshes-on-events`, a leaving session leaves the board, hook-free task-store capture, inline+capped free-text fields, conservative view-side de-clutter, the session-id linchpin, the durable snapshotted doc links, the card flags and per-version inbox card, and the turn-end phase backstop) and the tests that lock them. How the parts fit: the map `.claude/memory/agent-status-board.md`. ## Related To watch the messages agents send each other rather than their checklists, [Agent Messages](agent-messages.md) and [Overseers](overseers.md) are the sibling Agent Tools panels. The phase, gate and doc links on a card all come from a dev-pipeline run, so [Dev Pipeline (skill)](dev-pipeline.md) explains the run they describe, and [Agent lanes](agent-lanes.md) covers how concurrent agents are grouped. The board reads live on your phone too, which [Mobile Access](mobile-remote-access.md) covers.