The rius plugin also runs in the Codex
CLI. It was built and tested against codex-cli 0.144.1. The Claude Code
plugin is unchanged; Codex reads its own manifest (.codex-plugin/plugin.json)
and never loads the Claude Code hooks, commands or MCP config.
codex plugin marketplace add glassflow/rius-coding-agents
codex plugin add rius@rius-coding-agents
Codex copies the plugin to
${CODEX_HOME:-~/.codex}/plugins/cache/rius-coding-agents/rius/<version>/.
Codex runs no plugin hook until you approve it. Open /hooks in Codex and
trust the five rius hooks (SessionStart, UserPromptSubmit, PostToolUse,
Stop, SubagentStop). Until then nothing is traced, and nothing says so
except $rius:rius-status, whose Hooks: line counts the approved ones.
Approval is stored in config.toml and survived a plugin upgrade in our
tests. If a future version changes the hooks, Codex asks again.
Type $ and pick a skill. Codex never runs them on its own: each sets
allow_implicit_invocation: false, Codex's form of Claude Code's
disable-model-invocation, so only you can start one. Codex skills have no
per-skill tool allow-list, so Codex asks before running the command unless
your sandbox already allows it.
| Skill | What it does |
|---|---|
$rius:rius-login |
Browser sign-in; you pick the workspace |
$rius:rius-enable-here |
Trace this folder and everything under it, structure only |
$rius:rius-enable-content-here |
The same, with prompts, replies and tool output (secrets removed) |
$rius:rius-disable-here |
Stop tracing this folder |
$rius:rius-on / $rius:rius-off |
This session only |
$rius:rius-status |
What is on, why, the key, the hooks |
$rius:rius-logout |
Remove and revoke the stored key |
Login, logout and the enable/disable skills write to ~/.codex/rius/,
outside the workspace, and login needs the network. In the default sandbox Codex asks you to approve an escalation for
each of them.
If the sandbox will not allow it, run the same command in a terminal:
bash ~/.codex/plugins/cache/rius-coding-agents/rius/<version>/scripts/rius_ctl.sh login --agent codex
It prints a URL and a code. Approve in the browser, then run the same
command with login-wait in place of login.
Rius keeps its Codex key, settings and state in ~/.codex/rius/ under
your home folder as the operating system reports it, even when
CODEX_HOME points somewhere else. A repository can set environment
variables for Codex's hooks and commands, so CODEX_HOME (like HOME)
cannot be allowed to choose where the key is read from or which folders
are traced. Rius still reads $CODEX_HOME/config.toml, only to count the
approved hooks in $rius:rius-status.
Codex keeps its own key, separate from Claude Code's. Logging out of one does
not sign out the other. RIUS_API_KEY and RIUS_ENDPOINT in the
environment are ignored, as they are for Claude Code. To trace with a key
you minted in the console, store it from a terminal:
pbpaste | bash <plugin>/scripts/rius_ctl.sh use-key --agent codex # add --env staging for staging
See API keys.
One trace per Codex session (thread). A resumed session (codex resume,
codex exec resume) continues the same trace.
| Span | From the rollout file |
|---|---|
AGENT codex session |
the session; open until the session is closed (below) |
CHAIN turn |
one per turn: prompt, final reply, codex.turn.duration_ms, codex.turn.ttft_ms |
LLM <model> |
one per model call: input_tokens (includes cached), cache_read.input_tokens, output_tokens, reasoning.output_tokens |
TOOL <tool> |
one per call; a command that exits non-zero is error.type = exec_command.exit_<n> (exec.exit_<n> when a code-mode script ran it), an MCP error is <tool>.tool_error; a shell call (exec_command, or a code-mode script that calls it) carries rius.command.class (test, build, lint, package, git, other) and process.exit.code |
AGENT <role> |
a subagent, under the spawn_agent call that started it (multi_agent_v1, or the opt-in multi_agent_v2), with its own turns and calls |
CHAIN compaction |
one per compaction Codex records, in the turn it happened in (below) |
Resource attributes: service.name=codex, service.version (Codex's
version), process.working_directory, vcs.ref.head.name,
codex.originator, and telemetry.distro.name=rius-coding-agents with
the plugin's version. Content rules are the same as for Claude Code:
$rius:rius-enable-here sends structure only, $rius:rius-enable-content-here
adds content with secrets removed, and RIUS_CAPTURE_CONTENT=false turns
content off everywhere.
When Codex compacts a conversation it writes a compacted line, and Rius
sends it as a CHAIN span with gen_ai.operation.name set to compaction
(rius.compaction.*):
kindissummarize.executorisclientwhen thecompactedline carries the summary text Codex wrote, andproviderwhen its message is empty (a remote compaction, where the provider wrote the summary). The response id cannot tell them apart: Codex 0.162.1 sets it on both. The trigger (autoormanual) is not set: the rollout does not say.tokens.beforeis the prompt size of the last model call before it,tokens.afterthe size of the context Codex counts next, andtokens.droppedthe difference when it is positive. After a local compaction Codex counts its own estimate of the new context (atoken_countthat used no tokens); that istokens.after, and it is not a model call, so it gets noLLMspan (a remote compaction is counted the same way). Otherwise the next call's prompt size is used.tokens.beforeis a measured prompt size andtokens.aftermay be Codex's estimate, sotokens.droppedmixes the two. A compaction that follows another before any count arrived has notokens.before: the size known then is from before the older one.context_windowandid(Codex's window id) are set when known.- The span has no duration: Codex does not say how long a compaction took, so it starts and ends at its line. It is sent when the line is read and sent again, under the same span id, once the size after it is known.
- The first model call after a compaction has
gen_ai.conversation.compactedset; the later ones do not. summary.bytesis the size of the summary. The summary text (summary.text) is content: it is sent only where content is, with secrets removed and capped like the rest, and is not kept in the state file.
This was written from Codex's source (openai/codex: the compacted rollout
line and the token_count event), not from a recorded compaction: none of
the rollouts used here holds one, and the tests run on a synthetic rollout
(tests/fixtures/codex/synthetic_compaction.jsonl). The executor
rule (an empty message means the provider did it) was checked against the
0.162.1 source (compact.rs, compact_remote_v2.rs), and holds for that
version only; older writers were not read. A compaction written while no turn is
open (or inside a turn a forked session copied) is dropped.
Codex has no SessionEnd hook. A Codex trace is closed by the next Codex session you start with the same key, once the old session's Codex process has exited and it has been idle for an hour. The trace ends at the last thing the session did. Claude Code's own rule (12 hours) is unchanged.
The plugin registers the Rius MCP server as rius. Codex has no way to hand
it the stored key, so it signs in on its own through the server's OAuth:
codex mcp login rius
Do this once; it is a second sign-in, separate from $rius:rius-login.
The bundled server takes no key: its entry is just the URL, so Codex uses OAuth.
A repository can set these for Codex, so, as for Claude Code, they can only turn things off.
| Variable | Effect |
|---|---|
RIUS_CODEX_ENABLED |
false turns tracing off; true is ignored |
RIUS_CODEX_DEBUG |
logs to ~/.codex/rius/log/ |
RIUS_CODEX_MAX_ATTR_BYTES |
cap on each content attribute (default 32768); can only be lowered |
RIUS_API_KEY, RIUS_ENDPOINT |
ignored, as for Claude Code |
RIUS_CAPTURE_CONTENT, RIUS_SERVICE_NAME |
shared with Claude Code |
- Until the Rius backend learns the agent name, the key a Codex login mints and the connect page still say "Claude Code".
- LLM span start times are approximate (the previous event in the rollout).
- OpenAI does not report cache-write tokens, so none are sent.
- Code mode (
code_mode_host, on by default in codex-cli 0.144.1) runs every tool through oneexeccall that runs a script. Each such call is one TOOL span; the commands, patches and spawns inside it get no spans of their own. When the script throws, Codex reportsScript failedand the span is an error (exec.script_failed, message: the thrown error's first line). A command that fails inside a script that does not throw is read from the rollout, where codex-cli 0.162.1 writes anitem_completedevent for each command (CommandExecution, with itsexit_code, and no such event in the 0.144.1 rollouts checked): the span is an error (exec.exit_<n>, the first non-zero code) andprocess.exit.codeis set. A command that returns non-zero on purpose (rgwith no match,test -f) reads as an error too, as it does forexec_command. That event names no call, so the code is given to theexeccall that is the only call open, when the event's turn is the open turn and itsstarted_at_msis not before the call began; while calls run together, a failed command inside a script that does not throw still reads as success. In the one 0.162.1 rollout checkedstarted_at_msequals the end, so a command that began before the call and ended during it is not told apart. A call interrupted after such a command keeps its error. The call's output carries no exit code, and Codex's hooks were not checked for one.- Name (best effort). The span is named after the tools its script
calls (
exec_command,apply_patch,mcp__<server>__<tool>). The script is read by a small scanner, not a JavaScript parser: when it cannot be read to its end, is over 64 KB, or holds a/that could be a division or a regular expression with a quote or brace in between, the span is named plainexec. A name is only ever a tool called astools.<name>(in code, never text from a string or a comment. - Secret files (withholds when in doubt). A script whose text names a
secret-shaped file anywhere (
.env*,*.pem,*.key,id_rsa*,credentials*, ...: the names the other agents use) has its output replaced, whether the name is a path, a word of a command, a property such asobj.key, or a comment. This does not rest on the scanner, so it errs towards withholding the output of a harmless script; a script over 64 KB is withheld as well. Escapes in a quoted name ("\x2eenv") are decoded before the check. A name built while the script runs ('.' + 'env',String.fromCharCode) is still not seen. A script the scanner cannot read to its end is not withheld for that: it is only named plainexec. - Subagents (placement approximate, none dropped while the rollout
exists). A subagent spawned inside
execgoes under the call that was running when it was created and whose script can spawn one, else under any call that was running, else under the last one begun. While aspawn_agentcall is open its output (or, inmulti_agent_v2, thesub_agent_activityline) names the child exactly, so the child waits for it. If the session ends first, the child is placed when its trace is closed (under anexeccall as above, else under its spawner's open turn, else under the session), and its rollout is read then, unless the session was stopped. When severalexeccalls run at once nothing says which spawned which: they take their subagents in the order they began, among the subagents Rius has heard of so far, and a younger one heard of first can take the call that began first.
- Name (best effort). The span is named after the tools its script
calls (
- Interrupted turns are parsed from their documented shape but were not seen in a recorded run.
- A failed tool call is only marked as an error when it is a non-zero exit or an MCP error; other failures read as success.
codex exec --ephemeralwrites no rollout file, so it is not traced.