Codex Reasoning Reactor

Make reasoning budgets visible.

中文说明 · Manifesto · Architecture · Releases

Codex Reasoning Reactor turns an opaque model-and-effort picker into a compact, observable control surface. Across three project-defined profiles and six work modes, it presents local estimates for elapsed time, relative quota pressure, speed, task fit, and estimate confidence before work begins.

The same budget semantics power two surfaces:

• a supported, MCP-backed interactive Codex plugin;

• an optional, experimental Windows adapter inside the installed Codex window.

Independent community project. Estimates are local heuristics, not OpenAI billing, quota, latency, reliability, or model-performance guarantees. Luna, Terra, and Sol are Reactor profile names, not official product names or SKUs.

Why Reactor exists

A one-word effort setting hides several decisions: how long a task may take, how much relative budget it may consume, whether the task benefits from deeper serial work or parallel decomposition, and how confident the estimate is. Reactor makes those trade-offs visible at the moment of selection without pretending to know exact future cost.

The cosmic language is functional state encoding:

• celestial mass communicates task depth;

• cool-to-orange temperature communicates increasing budget;

• the energy trail communicates committed effort;

• the Ultra singularity communicates a change from single-task depth to parallel coordination.

Motion stays inside the control. The rest of Codex remains readable and familiar.

Related MCP server: cycles-mcp-server

Three profiles × six modes

Every profile exposes the same six-mode rail, for 18 selectable combinations.

Max and Ultra are not two points on the same scalar. Max allocates more depth to one task. Ultra changes the shape of execution: it adds parallelism and coordination overhead, may reduce wall-clock time for divisible work, and usually increases relative quota pressure.

What ships

• Local time-range, relative-quota, speed, fit, and confidence estimates.

• MCP tools for estimation, profile listing, the interactive control, and opt-in calibration.

• A responsive light glass control with real generated celestial and energy textures.

• Radio semantics, keyboard arrows, visible focus, 44 px targets, and reduced-motion behavior.

• A reversible Windows host adapter that reuses Codex's existing picker callbacks.

• Eight full-resolution generated source assets, optimized runtime derivatives, four sanitized demo captures, checksums, dimensions, and provenance.

• No hosted backend and no account-billing API.

Quick start: Codex plugin

Requirements: Git, Node.js 22+, a Codex build with plugin support, and the codex command on PATH.

git clone https://github.com/wangsiyi7/codex-reasoning-reactor.git
cd codex-reasoning-reactor
codex plugin marketplace add .
codex plugin add reasoning-budget@codex-reasoning-reactor

Or use the repository installer:

.\scripts\Install-Reactor.ps1

Start a new Codex task after installation so the skill and MCP tools are loaded. Try:

Show a reasoning budget for this task and compare Max with Ultra.

Run the standalone visual preview without installing anything:

npm run preview
# http://127.0.0.1:43191

Optional Windows native adapter

The plugin is the primary product. The native adapter is a local, version-sensitive bridge for users who want the same control inside the installed Codex picker.

cd native-adapter\windows
.\Start-Codex-Energy.ps1 -ForceRestart

It launches the installed Codex app with a loopback Chrome DevTools Protocol port, injects a renderer-only enhancement, and routes choices through callbacks already owned by Codex. It does not patch app.asar, replace signed files, or ship a custom Codex build. Stop the watcher or restart Codex normally to remove the injected interface.

On the currently verified host build, Ultra also selects Codex's existing priority service tier. That is a real host-side choice, not merely an animation; confirm the native trigger and account implications before using it.

Read the native-adapter safety and rollback guide before enabling it.

One engine, two renderers

flowchart LR
    E["Local budget engine"] --> M["stdio MCP server"]
    M --> W["Conversation widget"]
    E --> A["Optional Windows adapter"]
    A --> C["Existing Codex picker callbacks"]
    H["Opt-in local calibration"] --> E

The widget and adapter import the same model, mode, and estimation definitions. A second renderer never creates a second meaning.

Visual gallery

Visual inspiration

View the original concept by @xiaohu on X

That public post sparked the project's visual direction. We studied its orbital movement, progressive energy trails, material density, and cool-to-warm transitions, then independently designed and implemented a compact reasoning-budget system around those ideas. Discussion around the concept reinforced a more substantive goal: a reasoning control should communicate time, relative budget, speed, and confidence—not merely look impressive.

The original post and video are not mirrored, embedded as repository assets, or included in this project's licenses. See Inspiration and attribution.

Estimation boundary

The estimator combines task scope, prompt complexity signals, file count, context size, profile factors, mode factors, parallelizability, and optional local timing calibration. It returns a range and a relative multiplier against a project baseline—not a price or account-credit prediction.

See Budget model for the formula, confidence rules, and limitations.

Privacy and safety

Read PRIVACY.md and SECURITY.md.

Repository map

plugins/reasoning-budget/   Installable Codex plugin, MCP server, widget, tests
native-adapter/windows/     Optional renderer-only Windows bridge
artwork/originals/          Full-resolution generated source PNGs
assets/                     Asset provenance manifest and reproduction brief
media/                      Sanitized project captures used by GitHub docs
docs/                       Product philosophy, architecture, estimates, safety
scripts/                    Repository validation, asset manifest, installer
.agents/plugins/            Repo-local Codex marketplace

Development

npm test
npm run check
npm run assets:manifest

The normal test suite validates the budget engine, MCP protocol/resource, 18 profile combinations, generated PNG assets, adapter injection expression, repository structure, public-text hygiene, and provenance hashes. Live adapter verification is intentionally manual because it requires an installed Codex renderer.

Project docs

• Manifesto

• Architecture

• Budget model

• Native adapter

• Assets and provenance

• Accessibility

• Troubleshooting

• Roadmap

• Contributing

License

Source code is MIT licensed. Original project illustrations are offered under CC BY 4.0 to the extent contributors hold licensable rights. Third-party software UI and trademarks visible in project screenshots are excluded from the asset license. See ASSET_LICENSE.md and NOTICE.md.