Read-only live views of OmO task children,
one Herdr tab per running child.
Thanks to reeeeeee-dev for the idea and the original
herdr-core (hc) implementation:
gist: OmO/senpi extension — list running task children as herdr-core sub-agents.
This project is a maintained port of that work to the herdr CLI (protocol 22), with a few
additions: a tab per view, a keep window after the task ends, full thinking/Ask output, ANSI
highlighting, and incremental transcript reads.
Status: experimental, tested against OmO 5.1.70 and herdr 0.9.5 on Linux. It is a local developer tool, not a production service.
OmO's task tool runs children inside a shared task host. That host refuses outside
attachments, so a child is invisible in Herdr: you see one "working" agent row no matter how
many children are running.
This extension gives every running child its own viewer:
- polls the task store for records rooted at the current session;
- for a
runningchild, creates a Herdr tab namedtask · <name> [<id>]; - runs
view.pythere, which tails the child's session JSONL and prints a live feed; - reports the view to Herdr as an agent (
working/blocked); - keeps the view for 10 minutes after the child finishes (configurable, or until closed);
- closes everything on
session_shutdown.
The viewer is read-only. It cannot steer, abort, answer questions, or make a child appear
as blocked in the task itself.
| Component | Tested | Notes |
|---|---|---|
| OmO (senpi-based) | 5.1.70 | Must run the TUI inside a Herdr pane. Plain senpi has no task tool, so there is nothing to show. |
| herdr | 0.9.5 (protocol 22) | Uses herdr pane … / herdr tab … JSON commands. |
| python3 | 3.8+ | Standard library only; no pip installs. |
| OS | Linux | macOS should work; Windows is untested (PTY/quoting paths differ). |
The OmO process must have HERDR_ENV=1 and HERDR_PANE_ID set (Herdr does this for panes).
Without them the extension loads and does nothing.
-
Pick the agent config directory. OmO defaults to
~/.omo/agent; it honoursOMO_CODING_AGENT_DIR,SENPI_CODING_AGENT_DIR, andPI_CODING_AGENT_DIR. -
Copy both files into a subdirectory of its
extensions/folder. The directory name is arbitrary; this README usespython_omo_task_view:mkdir -p ~/.omo/agent/extensions/python_omo_task_view cp index.ts view.py ~/.omo/agent/extensions/python_omo_task_view/ chmod +x ~/.omo/agent/extensions/python_omo_task_view/view.py # optional; it runs via python3
-
Restart OmO completely and resume the session whose children you want to watch:
omo --session <session-id> # or omo, then /resume
A
/reloadinside a session does not pick up a newly added extension directory: only extensions present at session start are hot-reloaded. Restarting also keeps the taskroot_session_idmatching, which is what selects the children. -
Verify the load:
tail -20 ~/.omo/agent/hc-subagents/debug.log # load pane=w1:p2 env=1 ... pid=... # start reason=startup ... session=<id> ... # scan records=N live=M unreadable=0
(The state and log directory keeps the original
hc-subagentsname for compatibility with the ported gist.) -
Start a
taskin OmO and check Herdr:herdr tab list | grep 'task ·' herdr pane list | grep 'task ·'
A tab appears within
HC_SUBAGENTS_POLL_MS(5 s by default).
All settings are environment variables read by the OmO process (set them in the shell or the Herdr pane that launches OmO). The viewer inherits them when it starts.
| Variable | Default | Meaning |
|---|---|---|
HC_SUBAGENTS_POLL_MS |
5000 |
Task-record scan interval (minimum 1000). |
HC_SUBAGENTS_NEW_TAB |
1 |
1 = one Herdr tab per view; 0 = split beside the parent pane. |
HC_SUBAGENTS_KEEP_MS |
600000 |
How long a finished view stays (10 min). 0 = until you close it. |
HC_SUBAGENTS_THINKING |
1 |
0 hides thinking blocks. |
HC_SUBAGENTS_THINKING_STYLE |
full |
full (identifiers, keywords, markdown), light, off. |
HC_SUBAGENTS_TRUNCATE |
1 |
0 prints tool arguments and assistant text in full. |
HC_SUBAGENTS_MAX_BLOCK |
0 |
Character cap for one full block (thinking/Ask); 0 = unlimited. |
HC_SUBAGENTS_TASK_DIRS |
- | Extra task directories, :-separated, for a custom task.state_dir. |
HC_SUBAGENTS_PYTHON |
python3 |
Interpreter used for the viewer. |
HC_SUBAGENTS_COLOR |
1 |
0 (or NO_COLOR) disables ANSI colour. |
- Every
HC_SUBAGENTS_POLL_MSthe extension scans:<agentDir>/projects/*/senpi-task/tasks/,<cwd>/.omo/senpi-task/tasks/(legacy in-project store),- each directory in
HC_SUBAGENTS_TASK_DIRS.
- Records are re-read only when their
mtimeor size changed; unchanged files come from an in-memory cache. - A record belongs to the session when
root_session_idequals the session id (or, for older records,parent_session_iddoes). - Statuses
pending|running|paused|interruptedare "live";completed|error|cancelled|lostare terminal.
For a running child with host_session.session_path:
herdr tab create --workspace <parent workspace> --cwd <child cwd> --label "task · <name> [id]" --no-focus(orherdr pane splitwhenHC_SUBAGENTS_NEW_TAB=0).- Record the pane/tab id in the state file before running the viewer, so a timeout cannot orphan it.
herdr pane renameandherdr pane run python3 view.py --title … <record>.herdr pane report-agent --source hc-subagents:<task_id> --agent <name> --state working ….
view.py is a small, dependency-free tailer:
- opens the child's transcript and reads only new bytes every 0.5 s (a partial last line is buffered, capped at 4 MB);
- the whole file is read once at start (history), and again only if the file is
rewritten/truncated or the record points at a new
session_path; - prints assistant text, thinking, tool calls, failed tool results, and answers to Ask tools;
- keeps running after the task ends, printing
[completed]/[error]/… and a note; the extension closes the tab afterHC_SUBAGENTS_KEEP_MS; - if the same task runs again, the retired tab is replaced by a fresh view.
- State:
<agentDir>/hc-subagents/state/<sessionId>.json(pane/tab ids,endedAt). It lets a restarted TUI adopt live views instead of duplicating them. - Removing a view: close the tab/pane yourself, or wait for the keep window. A manually closed view is not reopened during that run.
session_shutdowncloses all views (fire-and-forget, so the quit budget is not blocked).- Logs:
<agentDir>/hc-subagents/debug.log(load, start, scans, open/close, errors). Delete it to reset.
- Compact one-liners for tool calls (
● eval {…}), capped user (400 chars) and assistant (2000 chars) text, capped tool errors (200 chars). - Thinking and Ask (
request_user_input,ask_user_question, plus the answer) are always printed in full. - Colors: cyan headings/tool names, dim-italic thinking, blue user text, green answers, red errors, syntax colouring for JSON and code, markdown (headings, bullets, quotes, rules, links, bold, italic).
NO_COLOR/HC_SUBAGENTS_COLOR=0disables colors.
| Symptom | Check |
|---|---|
| No views at all | debug.log has load pane=… env=1? If pane=none / env=unset, OmO is not inside Herdr. |
| Loaded but no rows | start line missing → the session is not TUI or is a task-child session (skipped). scan records=0 → no records rooted at this session; resume the right session. |
scan records=N live=0 while a task runs |
The record's root_session_id differs (new session after restart) or the store is custom: add it to HC_SUBAGENTS_TASK_DIRS. |
open failed … |
The log names the failing call. Common causes: herdr not in PATH, bad cwd, python missing. |
| View opens as a split | HC_SUBAGENTS_NEW_TAB=0 is set, or the running extension instance is old (restart OmO). |
| Finished tabs vanish immediately | Old extension instance; restart OmO. HC_SUBAGENTS_KEEP_MS must be visible to the OmO process. |
| Duplicate tabs for one child | A stale state file after moving directories; close duplicates. closeCopies also closes same-named views before reopening. |
| Colors missing | NO_COLOR/HC_SUBAGENTS_COLOR=0, or sys.stdout is not a TTY. |
- Local only. No network calls, no telemetry, no model requests from the viewer.
- Read-only. It reads task records and child transcripts and launches local
herdr/python3commands. It never writes to a child, its session, or its files. - Sensitive content. Child transcripts can contain source code, environment values, file paths, and secrets the child printed. The feed shows that text in a local Herdr pane; the debug log contains task names, ids, and errors (not transcript text). Treat screenshots of the feed as sensitive.
- No credentials. The extension stores no tokens and reads no auth files.
- Writes only to
<agentDir>/hc-subagents/(state + debug log). Delete that directory to remove all traces.
- Read-only: no steering, abort, permission answers, or real
blockedfrom a child dialog.blockedreflects the task record only. - One tab and one Python process per child. Many children mean many tabs.
- herdr 0.9.5 has no nested sub-agent tree; views appear as separate agents.
- A hard crash of OmO skips the shutdown hook; leftover tabs must be closed manually.
- Plain senpi sessions have no
tasktool, so nothing is shown there. - Custom
task.state_dirlocations must be listed inHC_SUBAGENTS_TASK_DIRS.
python3 -m py_compile view.py
bun build index.ts --target=node --outfile=/tmp/index.build.js # syntax checkManual check without OmO: create a task-record JSON with root_session_id set, point
host_session.session_path at a JSONL fixture, then run:
python3 view.py --title "task · demo [test]" /path/to/record.jsonFor the Herdr side, herdr pane split or herdr tab create plus herdr pane run is enough to
exercise the viewer; close the pane/tab afterwards.
- Idea and original herdr-core implementation: reeeeeee-dev — gist.
- OmO / senpi: code-yeongyu/oh-my-openagent, code-yeongyu/senpi.
- Herdr: herdr.dev.
- Discussion: code-yeongyu/senpi#6656.
MIT — see LICENSE.