monitor with orcr top

orcr top is the default view for tracking a running workflow or loop: a live tree that mirrors the path tree, with parent-to-child edges and statuses updating in real time. it is a status display, not a control surface. acting on an agent is what the CLI verbs (attach, send, kill) and herdr --session orcr are for.

orcr top [<pattern|uuid>] [-a <provider>] [--status <s>]
         [--managed|--unmanaged] [--loops]

┌ orcr · 9 agents (1 blocked) · 2 loops ─────────────────────────────┐
│ ▼ refactor                                                         │
│   ▼ phase_1                                                        │
│     ├─ file_1     ● working    claude · opus        2m14s          │
│     ├─ file_2     ● working    claude · opus        8m12s          │
│     └─ review     ◐ blocked ⚠  codex · question    11m03s          │
│ ▼ verify                                                           │
│   └─ checker      ● working    codex  ↖ refactor/phase_1/file_1    │
│ ▼ nightly · loop · next 09:00                                      │
│   └─ ▼ run r82c9s  ⟳ running · due 08:00 · 12m                     │
│       ├─ triage   ○ idle       claude               done 3m ago    │
│       └─ fix_1    ● working    codex                4m40s          │
│ ▼ unmanaged                                                        │
│   └─ main/w6_p1   ● working    claude               22m            │
│ ▶ idle (parked · 2)                                                │
│                                                                    │
│  [/] filter   [←→] collapse/expand   [q] quit                      │
└────────────────────────────────────────────────────────────────────┘

the layout

the tree is drawn by paths. every agent appears exactly once, at its path:

• level-1 segments are the top nodes (they match herdr's workspaces).
• loops appear with their active runs as subtrees (nightly above, with run r82c9s and the agents it spawned nested inside).
• parked agents collapse into a single Idle node so tidied-away agents do not clutter the active work.
• unmanaged agents sit under unmanaged, grouped by the session they were found in.

lineage is an annotation, never a second placement

parent-to-child edges come from the ORCR_PARENT_* env contract. a child can be created at an absolute path outside its parent's scope, so lineage is shown as a row annotation: a row whose parent lives elsewhere in the tree gets ↖ <parent path> (above, checker under verify points to refactor/phase_1/file_1). selecting a row highlights its parent and children wherever they sit. one node, one place; cross-scope edges are visible but never duplicate or re-root the tree. a parent that is a proper ancestor of the child gets no annotation, because the tree already shows that relationship.

glyphs and status

rows show the name, a status glyph and status, provider and model (plus the blocked kind when relevant), and age.

blocked agents float upward: they are the "needs a human" queue, so top surfaces them where you will see them.

keys and filters

interaction is navigation only:

• / filters by path pattern (the same grammar as everywhere else, resolved against your scope).
• arrows collapse and expand nodes and move the selection.
• q quits.

CLI flags pre-scope the tree before it opens, mirroring orcr agent ls:

orcr top "refactor/**"        # only that subtree
orcr top -a codex             # only codex agents
orcr top --status blocked     # only agents that need a human
orcr top --loops              # loops and their runs only
orcr top --managed            # exclude unmanaged agents

the filter node set matches the equivalent agent ls query exactly.

live-only by design

top shows active agents only. there is no --all flag; history is orcr agent ls --all. this is deliberate: top is for watching work in flight, and machine-readable state comes from orcr api snapshot or orcr agent ls --json.

rendering rides the same snapshot-then-subscribe protocol as the rest of the system: top opens one consistent snapshot at a snapshot_seq (agents, loops, runs, queue positions, GC clocks, parent edges), then applies the event stream from that sequence. it cannot miss or double-apply an update, and it reconnects and re-snapshots if the server stops or the cursor expires.

next

• run and manage agents: ls for the flat, greppable view.
• identity: paths and uuids: the path and glob model the tree is built from.
• schedule work with loops: the loops and runs shown as subtrees.