Codex Reasoning Reactor

<div align="center">

Make reasoning budgets visible.

中文说明 · Manifesto · Architecture · Releases

</div>

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.

Three profiles × six modes

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

Profile	Intended use
Luna	Clear, repeatable, high-volume work
Terra	Everyday engineering and balanced tool use
Sol	Ambiguous, complex, high-value work requiring judgment

Mode	Meaning
Light	Fast handling for narrow, well-defined work
Medium	Everyday balance between speed and depth
High	Stable default for multi-step engineering work
XHigh	Deeper planning and verification for difficult tasks
Max	More reasoning budget for one task
Ultra	Parallel subagent work for tasks that can be divided

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

Plugin · Medium	Plugin · Ultra

Native control · Medium	Native control · Ultra

<details> <summary>390 × 844 responsive verification</summary>

</details>

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

Surface	Mechanism	Data boundary	Rollback
MCP plugin/widget	Local stdio MCP + HTML resource	No hosted backend	Disable/remove plugin
Calibration	Opt-in JSONL history	Written only on explicit request	Delete local history
Windows adapter	Loopback CDP + renderer injection	No public listener	Stop watcher/restart Codex
X inspiration	External link only	No mirrored source media	Remove the link

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.