Skip to content

agentic: no way to see what a running agent is doing — add follow + live state for Codex and agy #1115

Description

@rickylabs

Summary

There is no way to see what a running Codex agent is doing right now. The pieces exist but the
observability question — "is this agent working, and on what?" — has no answer without hand-rolling
a parser over the session rollout.

This costs real time. Today a supervisor watched a research agent for 70 minutes, concluded it had
produced nothing, and came within one command of killing it. It was 25 of 27 sub-tasks complete
the output was landing in per-sub-agent worktrees, not the launching one. The only reason it survived
was a manual find across the repo root and an ad-hoc Python parse of
~/.codex/sessions/**/rollout-*.jsonl to read its agent_reasoning stream.

That parse should be a command.

What exists today

Tool Answers Does not answer
agentic:codex-status daemon health, appServerProcesses count, list of session file paths which agent is which, what any of them is doing, whether any is progressing
agentic:codex-watch --mode git "the worktree got a git event" whether the agent is alive, idle, or hung — its own header says git activity "does NOT say the agent stopped working"
agentic:codex-watch --mode turn "the current turn finished" (task_complete in the rollout) anything before that moment — it is a waiter that exits, not a follower
runtime/rollout-report.ts post-hoc rollout reporting live state

So: we can wait for an agent to finish, and we can inspect after the fact. We cannot look at one
mid-flight.

Proposal — agentic:codex-follow

A live tail over a running agent's session rollout, resolved the same way codex-watch already
resolves it (--thread-id <uuid> → newest matching rollout, or --rollout <path>).

deno task agentic:codex-follow --thread-id <uuid> [--since 5m] [--format pretty|json]

Streams the events that actually say what an agent is doing — agent_reasoning, agent_message,
command invocations and their exit status, file writes — filtered so it is readable rather than the
raw 4 MB JSONL. Exits when the session ends.

And extend codex-status to answer the triage question directly, per live session:

  • thread id, model, effort, cwd/worktree
  • state: working | idle | no-activity-for-N — derived from the rollout's last event timestamp,
    not from process liveness
  • last reasoning line, truncated
  • artefact evidence: last commit on its branch, or last file written

The distinction that matters and that nothing currently encodes: liveness is not progress. A
process can sit at 0% CPU with an open socket indefinitely, and an agent can be quietly productive
while its launching worktree stays empty. Both were misread today.

Why this is worth building rather than documenting

The information is already on disk in a stable format. The gap is purely that every supervisor —
human or agent — has to rediscover the rollout path, the event schema, and the task_complete
marker on their own. It took a supervisor most of an hour to find codex-watch --mode turn by
grepping the tool's source comments, and that tool still does not do the thing needed.

The failure modes it prevents are expensive and asymmetric: killing a nearly-finished agent destroys
an hour of work, and letting a hung agent run silently wastes the same.

Acceptance

  • agentic:codex-follow --thread-id <uuid> streams a readable live view of a running agent
  • It resolves the rollout by thread id, matching codex-watch's existing resolution
  • agentic:codex-status reports per-session state (working / idle / stalled-for-N) derived
    from rollout recency, not process liveness
  • codex-status reports each session's worktree and last artefact (commit or file write)
  • Documented in .llm/tools/agentic/README.md and the harness tooling index, so it is findable
    without reading source comments
  • A supervisor can answer "is this agent working, and on what?" in one command

Provenance

Wave-four orchestration, 2026-08-03. Raised by the owner after a supervisor spent significant time
discovering that codex-watch --mode turn existed at all, and nearly killed a 25/27-complete agent
for want of a live view.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions