Oko
Oko/Docs

Command reference

oko work board

Shows one supervisor's work as its transcripts show it: every stream it delegated, what each is doing now, what it waits on, who idles, who duplicates whom, which dependency holds the most streams, and what each stream costs. Nothing on it is what a stream reported about itself.

Invocation#

Command
oko work board [--supervisor SESSION] [--since TIME | --hours N] [--at TIME] [--idle-minutes N] [--send] [--json]

Inputs and options#

  • The supervisor is --supervisor, else the agent session the command runs in. A stream is every session the supervisor delegated work to: its transcript lies below the supervisor's transcript folder and its parentSession chain reaches it (a delegate's own delegates are streams too, named `Parent.Child`). Its assignment is the first line of the supervisor's spawn that started it; its orders are the supervisor's later direct messages to it.
  • The window is --since (RFC 3339) or the last --hours, else the 24 hours before --at. --at reads every transcript as it stood at that moment, so the board answers what it would have shown then; without it, now.
  • Each stream's state comes from its own last call and result: `done` (its turn ended or its run exited), `failed` (its last turn ended in a provider failure), `waiting` (a wait call or a polling call has not returned), `running` (another call has not returned), `working` (the model is composing), `silent` (none of these and no record for longer than the idle interval).
  • What a stream waits on: the dependencies the supervisor stated in its own words (`oko work board depend`); the blockers register's open waits recorded in its session (`oko blockers record --waits-on`), held by the stream whose session owns the defect; its open wait call, on every agent it sent a direct message and has not heard from since; its open polling call, on the operation's program group (`stado change` is the submit queue); and every operation whose latest runs in it failed twice in a row (its exit, or a failure line of Stado's wait mechanism in its output) with no success of it in any stream since.
  • What a stream changed: every file its edit and write calls name, placed in its repository with an export's own prefix taken off (`<repository>/.build/<name>/…`), and every file of the commits its commit calls made, read from the checkout with git.
  • Cost: each assistant record's usage, priced as `oko telemetry tokens` prices it (list prices; a model no rule prices leaves the cost inexact and is named).

Output and state effect#

  • Prints the supervisor and its cost, the counts (streams, in progress, working, running, waiting, done, failed, silent, blocked, idle now), the spend (tokens, by counter, and dollars over the streams' wall time), the critical path (the dependency most streams wait on, directly or through others, the streams waiting and its chain onward), every flag in the order it was raised, and one line per stream: state, minutes since it last moved, its current operation, cost, wall and idle minutes, assignment.
  • Flags: `idle` (a stretch it only waited, longer than --idle-minutes, default 30); `sharedWait` (two or more streams waited past the interval on the same agent or the same polled program group); `dependency` (three or more streams wait on one dependency, with when the third began); `duplicate` (two streams of different lines of work changed the same component, the first four parts of a path in its repository, or named the same defect, within two hours, unless a commit only carried another stream's uncommitted edit, or more than two lines changed that component in those hours); `revived` (a stream that had finished took another turn because a broadcast reached it, with the tokens and dollars that turn spent); `silent`; `claim` (the supervisor said of one stream something a message it sent that stream only afterwards says more closely than any message before, compared by meaning with Oko's own embedding model).
  • --json prints {supervisor: {session, transcript, cost, messagesSent, spawned}, at, since, idleMinutes, counts, totals: {tokens, counters, costUsd, costExact, wallMinutes}, streams: [{id, session, parent, transcript, assignment, assignedAt, orders, lastOrderAt, state, blocked, current: {tool, intent, operation, at, open, minutes, failed, result}, lastProgressAt, minutesSinceProgress, startedAt, lastAt, wallMinutes, calls, failedCalls, cost: {tokens, counters, costUsd, exact, unpricedModels}, idleMinutes, waits, waiting, revivals, defects, components, unplacedEdits}], dependencies: {criticalPath: {head, label, waiting, chain}, hubs, cycles, waits: [{from, to, source, since, detail}], stated}, flags: [{key, kind, streams, at, text, detail}], claims: {checked, flagged, compared | refused}, touches, unread, sent}.
  • --send hands each flag raised within the idle interval before the board's moment, and not handed before, to the supervising session as Oko's own routines hand a message (`oko sessions send`'s contract, kept as a post); what was handed is kept in work-board-sent.json beside the defect register (`OKO_WORK_BOARD_SENT`), so a flag that still holds is said once. `sent` lists each hand-over or its refusal.
  • Oko Desktop → Blockers → Work board shows the same answer through the native API (`blockers` domain, `work_board {supervisor, hours?, at?, idle_minutes?}`).

Refusals and safe exits#

  • `oko work board runs in no agent session; name the supervising session with --supervisor SESSION` (exit 2) and `no transcript of the supervising session <id> on this machine; looked in <roots>. The session id may be mistyped or cut short, or its transcript lives on another machine or was moved; name a session whose transcript is here with --supervisor SESSION (the id ends a transcript's file name in those folders)` (exit 1).
  • `oko work board takes --since or --hours, not both: each sets where the window begins; give one of them`, `oko work board: --at takes an RFC 3339 time such as 2026-10-29T19:58:00Z, got <text>: <cause>` and any unknown flag (exit 2).
  • A register that cannot be read (blockers, defects) refuses naming it. A transcript or checkout that cannot be read is listed under unread with its cause and the rest stands. When Oko's embedding model is not installed the claim check says `checked: false` with `run oko requirements embedder install`, and the rest stands.

CLI reference#