How do I track subagents in Codex (beta)?

Rius traces subagents that Codex (beta) starts, as nested spans under the call that spawned them, once you install the Rius plugin and turn tracing on for a folder. Each subagent appears in the session’s trace with its own turns and calls. Structure-only tracing is enough to see subagents, so you do not need to send prompts or replies.

How it works

The Rius plugin traces Codex (beta) CLI sessions, with one trace per session. When Codex starts a subagent, the trace records two things:

• A tool span named spawn_agent, which is the call that started the subagent.
• An agent span under it for the subagent itself, with its own turns, model calls and tool calls.

The tree looks like this:

AGENT   codex session
└─ CHAIN  a turn: one prompt and everything it caused
   └─ LLM   a model call: model, input, cached, output, and reasoning tokens
      ├─ TOOL  a tool call. A command that exits non-zero is an error.
      └─ TOOL  spawn_agent: the call that started a subagent
         └─ AGENT  the subagent, with its own turns and calls

The subagent’s model calls are recorded like any other model call, with model name, token counts and cost. Cost is worked out from token counts at API rates, so on a ChatGPT plan it measures usage, not what you pay.

The plugin hooks into Codex at five points: SessionStart, UserPromptSubmit, PostToolUse, Stop and SubagentStop. SubagentStop is the one that fires when a subagent finishes. Codex runs none of these hooks until you trust them.

Set it up

1. Install the plugin from a terminal. It needs Codex with plugin support, plugin 0.6.0 or later, and Python 3.9 or later on your PATH.

   codex plugin marketplace add glassflow/rius-coding-agents
   codex plugin add rius@rius-coding-agents

2. Trust the hooks. In Codex, open /hooks and trust all five rius hooks, including SubagentStop. Until you do, nothing is traced and Codex does not tell you.

3. Sign in. Type $rius:rius-login, approve the sandbox escalation, then pick a workspace in the browser and click Connect.

4. Turn tracing on for the repo where you use subagents with $rius:rius-enable-here. This sends structure only, which already includes subagents. Use $rius:rius-enable-content-here if you also want prompts, replies and tool output, with recognised secrets removed on a best-effort basis.

5. Run $rius:rius-status. The Hooks: line should count five approved hooks, and the reason line tells you whether the folder is traced.

6. Work as usual, then open the session in the trace list at console.rius-glassflow.com.

For the full sign-in, folder rules and settings, see the Codex (beta) guide.

What you get

• Traces. Each Codex (beta) session is one trace, and the waterfall shows the spawn_agent call with the subagent’s turns and calls nested below it. Resuming with codex resume or codex exec resume continues the same trace.
• Agents. Sessions appear as an agent named codex on the Agents page, and an open session is a live instance. The agent’s trace, error and cost figures count a session once its trace is closed.
• Users. From plugin 0.6.2, each span carries user.id set to your sign-in email, so sessions land under your name on the Users page.
• Questions in plain language. Run codex mcp login rius once, a second sign-in separate from the one that sends traces. Then ask Codex about your recent sessions, for example which one used the most tokens or which one failed.

What Codex (beta) tracing does not report:

• OpenAI does not report cache-write tokens, so none are shown.
• A failed tool call is marked as an error only when a command exits non-zero or an MCP tool fails. Other failures look like success.
• Model-call start times are approximate.
• Codex does not tell the plugin when a session ends. A trace closes when you start your next session on the same key, once the old process has exited and been idle for about an hour, so until then it shows as in progress.
• codex exec --ephemeral sessions are not traced.
• The plugin never marks the session itself as failed. A session with a failed step is badged recovered.
• Windows is untested for Codex (beta).

When something else fits

If your team mostly uses Claude Code, Track Claude Code usage and cost across a team shows subagents per developer and per session, with tokens and cost on each. To compare how Claude Code, Codex (beta), Cursor (beta) and OpenHands connect, see Coding agents.

Related