Skip to content

About

Read-only live views of OmO task children in Herdr tabs (ported from reeeeeee-dev's herdr-core gist)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

python_omo_task_view

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.

What it does

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 running child, creates a Herdr tab named task · <name> [<id>];
  • runs view.py there, 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.

Requirements

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.

Install (agent checklist)

  1. Pick the agent config directory. OmO defaults to ~/.omo/agent; it honours OMO_CODING_AGENT_DIR, SENPI_CODING_AGENT_DIR, and PI_CODING_AGENT_DIR.

  2. Copy both files into a subdirectory of its extensions/ folder. The directory name is arbitrary; this README uses python_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
  3. Restart OmO completely and resume the session whose children you want to watch:

    omo --session <session-id>     # or omo, then /resume

    A /reload inside a session does not pick up a newly added extension directory: only extensions present at session start are hot-reloaded. Restarting also keeps the task root_session_id matching, which is what selects the children.

  4. 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-subagents name for compatibility with the ported gist.)

  5. Start a task in 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).

Configuration

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.

How it works

Task discovery

  • Every HC_SUBAGENTS_POLL_MS the 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 mtime or size changed; unchanged files come from an in-memory cache.
  • A record belongs to the session when root_session_id equals the session id (or, for older records, parent_session_id does).
  • Statuses pending|running|paused|interrupted are "live"; completed|error|cancelled|lost are terminal.

Opening a view

For a running child with host_session.session_path:

  1. herdr tab create --workspace <parent workspace> --cwd <child cwd> --label "task · <name> [id]" --no-focus (or herdr pane split when HC_SUBAGENTS_NEW_TAB=0).
  2. Record the pane/tab id in the state file before running the viewer, so a timeout cannot orphan it.
  3. herdr pane rename and herdr pane run python3 view.py --title … <record>.
  4. herdr pane report-agent --source hc-subagents:<task_id> --agent <name> --state working ….

Viewer

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 after HC_SUBAGENTS_KEEP_MS;
  • if the same task runs again, the retired tab is replaced by a fresh view.

State and lifecycle

  • 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_shutdown closes 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.

Rendering

  • 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=0 disables colors.

Troubleshooting

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.

Security and privacy

  • 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/python3 commands. 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.

Limitations

  • Read-only: no steering, abort, permission answers, or real blocked from a child dialog. blocked reflects 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 task tool, so nothing is shown there.
  • Custom task.state_dir locations must be listed in HC_SUBAGENTS_TASK_DIRS.

Development

python3 -m py_compile view.py
bun build index.ts --target=node --outfile=/tmp/index.build.js   # syntax check

Manual 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.json

For 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.

Credits

License

MIT — see LICENSE.

About

Read-only live views of OmO task children in Herdr tabs (ported from reeeeeee-dev's herdr-core gist)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages