Skip to Content
Rius

How do I set up tracing for Codex (beta)?

Rius traces Codex (beta) sessions with its plugin: install it, trust five hooks, sign in, and enable a folder, and each session arrives as one trace. Installing sends nothing, and tracing stays off for every folder until you enable it. The plugin needs version 0.6.0 or later and Python 3.9 or later on your PATH. It runs on macOS and Linux, and Windows is untested for Codex (beta).

How it works

  • The plugin hooks into Codex (beta) and sends one trace per session. The trace holds every turn, every model call with its tokens, every tool call, and any subagents Codex started. Prompts and replies are added only in a folder you enable for content.
  • Each folder has its own rule. By default a folder sends structure only: the span tree, timing, model names, tokens, cost, tool names and error types. You can opt a folder in to also send prompts, replies, and tool inputs and outputs, with recognised secrets removed. Redaction is best effort.
  • Sessions appear on the Agents page as an agent named codex. From plugin 0.6.2, each span carries the email you signed in with, so sessions show under your name on the Users page.
  • 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. Until then it shows as in progress.
  • Cost is worked out from token counts at API rates, so it is not what you pay on a ChatGPT plan.

The full reference is in the Codex (beta) guide. The same plugin also covers the other agents on the Coding agents page.

Set it up

  1. Install the plugin. Run both lines in a terminal.

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

  2. Trust the hooks. Open /hooks in Codex (beta) and trust the five rius hooks: SessionStart, UserPromptSubmit, PostToolUse, Stop and SubagentStop. Until you do, nothing is traced and Codex gives no warning. Codex keeps the approval across plugin updates and asks again if a new version changes the hooks.

  3. Sign in. Type $rius:rius-login and approve the sandbox escalation. In the browser, sign in or sign up, check that the page shows the same code and your machine name, choose the workspace this machine sends sessions to, and click Connect. This stores one key for the machine, readable only by you, that can send traces but not query them.

  4. Turn tracing on for a folder. In your repo, run one of these, then check the result.

    $rius:rius-enable-here
$rius:rius-status

    Use $rius:rius-enable-content-here instead if you also want prompts, replies and tool output. $rius:rius-disable-here stops a folder, and a disabled folder beats any enabled parent. $rius:rius-on and $rius:rius-off switch tracing for the current session only.

  5. Check the first session arrives. Work in Codex (beta) as usual, then open the trace list at console.rius-glassflow.com. Your session is there, in progress until it closes.

  6. Fix a missing session. Run $rius:rius-status and read it:

    • If the Hooks: line counts fewer than 5 approved hooks, trust the rest in /hooks.
    • If the Reason line says no path rule matches, run $rius:rius-enable-here in that folder.
    • If it says there is no key, run $rius:rius-login.

  7. Optional: ask about your sessions. Run codex mcp login rius once. This is a second sign-in, separate from $rius:rius-login. Then ask Codex (beta) something like “list my recent Codex sessions in Rius”.

What you get

  • One trace per Codex (beta) session in your workspace, with model calls, tool calls and subagents as spans.
  • Tokens and cost on every model call, shown as list-price estimates. OpenAI does not report cache-write tokens, so none are shown.
  • Folder-level control over what leaves your machine: structure only by default, content only where you opt in.
  • A key you can see and revoke under Settings → API keys in the console, listed as Codex: <your email> (<machine>).
  • A clean exit: $rius:rius-logout revokes the key and deletes it from the machine.

One gap to know: a failed tool call is marked as an error only when a command exits non-zero or an MCP tool fails.

When something else fits

If you also use Claude Code or Cursor (beta), the same plugin covers them, each with its own sign-in and folder rules, though Cursor sessions carry no tokens or cost. For OpenHands you need no plugin, only three environment variables, and the Coding agents page compares all four. If you need Windows today, Claude Code is the agent whose plugin runs there.

Still stuck? Get help

Last updated on
Quickstart