How do I track failed tool calls in Codex (beta)?

Rius records every tool call in a Codex (beta) session as its own step in the session’s trace, and marks a call as an error when a command exits non-zero or an MCP tool fails. You turn tracing on per folder with the Rius plugin, then find the failed steps in the trace list and the trace waterfall. Other kinds of tool failure in Codex (beta) are not marked as errors, so they look like successes.

How it works

The Rius plugin reads each Codex (beta) CLI session and sends it as one trace. The trace is a tree of steps:

• The session is the root.
• Each turn, meaning one prompt and everything it caused, sits under the session.
• Each model call sits under its turn, with its tokens.
• Each tool call sits under the model call that made it, as its own step.
• A subagent that Codex starts appears nested under the spawn_agent call that started it, with its own turns and calls.

A tool call is marked as an error in two cases: a command that exits non-zero, and an MCP tool that fails. That marked step is what you track.

The session itself is never marked as failed. A session with at least one failed step gets a recovered badge in the trace list. On the Users page it counts toward Error rate, not Failed traces. Keep that in mind if you track failures by counting failed traces, because a session full of failed commands does not appear there.

What each failed step carries depends on the folder mode:

• Structure only (default): the span tree, timing, status, tool names and error types.
• With content: the same, plus tool inputs and outputs, so you can read the command that failed. Rius removes the secrets it recognizes first, on a best-effort basis.

The Agents page lists these sessions under an agent named codex. Its error figures count a session only once its trace is closed. Codex does not tell the plugin when a session ends, so the next Codex session you start on the same key closes the old trace, after the old process has exited and been idle for about an hour. Until then the trace shows as in progress.

Set it up

1. Install the plugin from a terminal. Installing sends nothing.

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

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

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

4. In the repo you want to watch, run $rius:rius-enable-here for structure only. Run $rius:rius-enable-content-here instead if you also want the inputs and outputs of failed tool calls. Then run $rius:rius-status to confirm the folder is traced. Its Hooks: line counts the approved hooks, so check it if a session does not show up.

5. Work as usual. Then open the session in the trace list in the console and look through the waterfall for steps marked as errors. Sessions with a failed step carry the recovered badge.

6. To ask instead of browsing, sign in to the MCP server once. This is a second sign-in, separate from $rius:rius-login.

   codex mcp login rius

   Then ask Codex in plain language, for example “Show me my last failed session and which command went wrong.”

The full plugin setup, including sign-out and troubleshooting, is in the Codex (beta) guide. Codex (beta) needs plugin 0.6.0 or later and runs on macOS or Linux. Windows is untested.

What you get

• Each failed command or failed MCP tool call as its own marked step, inside the turn and model call that caused it.
• The tool name and error type on every failed step, even in structure-only mode.
• The tool input and output on failed steps when you enable a folder with content.
• The recovered badge on any session that had a failed step, so you can spot sessions worth opening.
• Tokens and cost on the model calls around the failure, so you see what a bad run spent. Cost is worked out from token counts at API rates, so on a ChatGPT plan it measures usage, not what you pay.
• Answers over MCP, from inside Codex, about your latest failed session.

If your team also uses Claude Code, Track Claude Code usage and cost across a team shows the same per-developer and per-session views for that agent. Coding agents compares what each supported agent reports.

Two gaps affect failure tracking. A tool failure that is not a non-zero exit or a failed MCP tool looks like a success in the trace. Sessions started with codex exec --ephemeral are not traced at all, because Codex keeps no record of them for the plugin to read.

When something else fits

• If you need every kind of tool failure flagged, not only non-zero exits and failed MCP tools, check the step’s output in a content-enabled folder, since other failures are not marked.
• If you need failed sessions counted under Failed traces, Codex (beta) will not give you that, because the plugin never marks the session itself as failed. Use the recovered badge and the Error rate instead.

Related