X-ray visualization of a terminal showing code, progress bars, and circuit-like data traces flowing from source to output

codexray

X-ray vision into a Codex run — live progress + real token usage from Claude Code.

Before & After

See inside the run

codex:codex-rescue

$ codex --model gpt-5.5 "refactor auth" [blocking... no output for 47s] Done. (no token count)

codexray

$ codexray run "refactor auth" --model gpt-5.5 ● Running codex exec --json ▸ Reading src/auth/middleware.ts ▸ Reading src/auth/session.ts ▸ Writing src/auth/middleware.ts ✓ Complete tokens 16,478 in · 27 out · 20 reasoning · 16,505 total

Capabilities

Built for visibility

Live progress

A tail-able progress file streams Codex activity into your Claude session in real time. No more staring at a silent terminal.

Real token usage

Captures Codex token-usage events that the stock plugin drops. Input, output, reasoning, cached — every number accounted for.

Drop-in subagent

codexray:codex-runner replaces codex:codex-rescue with a single Agent dispatch. Same interface, full visibility.

Stable transport

Built on codex exec --json, the stable surface that OpenAI's own SDK wraps. No undocumented APIs.

Optional streaming

The Monitor plugin pushes live Codex progress directly into the Claude Code conversation. Requires Claude Code >= 2.1.105.

Zero runtime deps

Pure ESM with JSDoc types checked by tsc --checkJs. Nothing to install beyond Node >= 18.17 and the Codex CLI.

Get started

Two commands, zero config

Add the plugin from the marketplace, install it, and you're done.

Claude Code

❯ /plugin marketplace add lidge-jun/codexray
❯ /plugin install codexray

Then verify: codexray doctor

Requires Node >= 18.17 and codex CLI on PATH (or CODEX_BIN).

Setup

Configure your agent

Just ask

The codex-run skill auto-triggers. Try these prompts:

Delegate this refactor to Codex and show me the token usage.
Have Codex investigate this bug (read-only) and report back.
codexray로 이 모듈 리팩터하고 토큰도 알려줘

Make it the default

Paste into ~/.claude/CLAUDE.md or a project CLAUDE.md:

CLAUDE.md

## Delegating to Codex
Route Codex work through codexray. The recommended default is a main-session
background run (`codexray run --json …` via Bash run_in_background) — Claude reads
only the final result, and live streaming is free (handled by the Node process, not
a Claude agent). For a subagent shape, use codexray:codex-runner — a Haiku thin
launcher that returns a job handle only, never piping Codex output through itself.
Pass --model / --effort by task weight (e.g. --model gpt-5.5 --effort high for
substantial work; --model gpt-5.3-codex-spark --effort medium for quick lookups).
Add --sandbox read-only for investigation-only tasks.

Zero-overhead streaming

Live progress is free. Streaming is handled by a local Node process parsing codex exec --json — no Claude agent is involved, so watching a run costs zero model tokens.
Main session reads only the result. Launch via Bash run_in_background, get notified on completion, and read the final output once. No middleman, no token pass-through.
Subagent is a thin launcher. codexray:codex-runner runs on Haiku and returns only a job handle (jobId + resultPath) — it never pipes Codex output through itself.

Status

Verified

Tests pass

tsc errors

Live smoke runs

16,505

Tokens captured

Usage

Slash commands & CLI

Claude Code
# Run a task
❯ /codexray:run "refactor the auth module"

# Check progress
❯ /codexray:status

# Get the result + token usage
❯ /codexray:result

# Or use CLI flags
❯ codexray run --model gpt-5.5 --effort xhigh "fix the flaky test"

Also available: /codexray:cancel, codexray watch, codexray list, codexray doctor.

Tuning

Model, effort & speed

Three flags control cost, latency, and thoroughness. They map 1:1 to Codex CLI flags.

`--model <id>`

The Codex model. Use gpt-5.5 for substantial work. The fast, low-cost, text-only model for quick lookups is gpt-5.3-codex-spark.

Maps to Codex -m

`--effort <level>`

Reasoning effort: minimal | low | medium | high | xhigh. Lower is faster & cheaper; higher is more thorough.

Maps to Codex -c model_reasoning_effort

`--fast`

Requests the fast service tier (service_tier=fast) for lower latency where your account supports it.

Boolean flag, no Codex equivalent

Fast / cheap

Quick lookups, search, simple edits

--model gpt-5.3-codex-spark --effort low --fast

Substantial

Implementation, deep debugging, design

--model gpt-5.5 --effort xhigh

Examples

# Fast lookup (read-only)
❯ codexray run "find where auth is validated" --model gpt-5.3-codex-spark --effort low --fast --sandbox read-only

# Substantial implementation
❯ codexray run "implement the retry policy" --model gpt-5.5 --effort xhigh