README.md

A personal Codex profile that keeps small work on the root, routes demanding work to an explicit Sol effort tier, and keeps child logs out of the main context.

简体中文 · benchmark evidence · ClaudeX Flow ↗ · v0.1.0

Community project. Not an official OpenAI repository.

The benchmark is deliberately narrow: one randomized pair, same model, same effort, same repository commit, same held-out test. It is evidence that the small-task policy avoided unnecessary work—not a general latency or cost claim. Inspect the prompt, patches, commands, and usage record.

Install

git clone https://github.com/raydocs/codex-sol-orchestration.git
cd codex-sol-orchestration
./install.sh

Then restart Codex or start a new task.

The installer preflights the complete configuration before changing live files. It backs up every managed file under ~/.codex/backups/, installs the three tier profiles and runner, patches only selected config.toml keys, and records hashes for safe uninstall.

One policy, four routes

Work shape	Route	Effort	Boundary
Small or tightly serial	Root	High	Executes directly
Read-only discovery	Router	Medium	No file edits
Implementation, debugging, review	Worker	High	Explicit mutation scope
Architecture or conflicting evidence	Arbiter	XHigh	Decides; does not implement

GRILL is conditional. The root asks only when ambiguity can change success criteria, public interfaces, data integrity, irreversible behavior, or material cost. Facts discoverable from the repository are resolved before the user is interrupted.

What changes in practice

No ceremonial delegation. One-file edits and short serial work stay on the root.

No mandatory scout. Router is used only when read-only discovery removes meaningful critical-path work.

Exact effort, recorded at runtime. codex-tier-exec verifies the profile and emits a route receipt with role, model, effort, sandbox, and artifact paths.

Logs leave the root context. Full child output goes to ~/.codex/tier-artifacts/; the parent receives a bounded result.

Acceptance stays centralized. Children investigate, implement, or decide one bounded slice. Root integrates, verifies, and accepts.

Run a tier directly

~/.codex/bin/codex-tier-exec router  /path/to/repo @router-prompt.txt
~/.codex/bin/codex-tier-exec worker  /path/to/repo @worker-prompt.txt
~/.codex/bin/codex-tier-exec arbiter /path/to/repo @arbiter-prompt.txt

A successful launch starts with a machine-readable receipt:

CODEX_TIER_ROUTE role=worker model=gpt-5.6-sol effort=high \
mechanism=codex-tier-exec sandbox=workspace-write mode=compact

Useful output controls:

CODEX_TIER_ARTIFACT_DIR=/absolute/path/to/artifacts \
CODEX_TIER_RESULT_MAX_LINES=12 \
CODEX_TIER_RESULT_MAX_CHARS=4000 \
~/.codex/bin/codex-tier-exec worker /path/to/repo @prompt.txt

Codex CLI 0.144.3 loads --profile NAME from $CODEX_HOME/NAME.config.toml. The installer renders router.config.toml, worker.config.toml, and arbiter.config.toml at those exact locations.

Child contract

Every delegated brief defines:

1. one bounded objective;
2. a concrete done condition;
3. relevant paths and dependencies;
4. constraints and material risks;
5. allowed and forbidden mutations;
6. required verification evidence.

Leaf results stay under 12 non-empty lines unless detail is requested. Full diffs, logs, and extended analysis belong in artifacts.

Safety and rollback

~/.codex/bin/codex-sol-uninstall

The uninstaller checks every managed file against its installed hash. If a profile, instruction, runner, or config.toml changed after installation, it stops instead of overwriting the edit. --force restores the pre-install backup and discards later managed-file changes.

The repository contains no API keys, authentication files, sessions, databases, or user-specific Codex state. Do not attach auth.json, config.toml, session data, or tier logs to issues.

Requirements and limits

• Codex CLI with standalone profile support; tested with codex-cli 0.144.3.
• Access to gpt-5.6-sol with medium, high, and xhigh effort levels.
• macOS or Linux, Bash, and Python 3.11+.
• multi_agent_v2 remains disabled until the runtime can prove child selection and recorded effort.
• The external tier runner gives precise model/effort control and context isolation. Parallel speedup still depends on truly independent work and the parent runtime's ability to overlap calls.

Model availability varies by account and workspace. Do not install the profile unchanged if gpt-5.6-sol is unavailable.

Configuration written by the installer

model = "gpt-5.6-sol"
model_reasoning_effort = "high"
model_instructions_file = "/absolute/path/to/.codex/instruction.sol.md"

[features]
hooks = false
multi_agent = true
multi_agent_v2 = false

[agents]
max_threads = 6
max_depth = 1
interrupt_message = true

Repository map

instruction.sol.md          root policy
agent-instructions/         bounded leaf contracts
profiles/                   Router, Worker, Arbiter profile templates
bin/codex-tier-exec         verified tier runner
scripts/patch_config.py     narrow TOML patcher
benchmarks/                 prompts, patches, evaluation, usage evidence

Sibling workflow

ClaudeX Flow brings the same efficiency-first discipline to Claude Code: a dynamically resolved GPT-5.6 Sol Supervisor, bounded Grok 4.5 workers, zero-model admission, disjoint write leases, compact integration receipts, and one root-owned verifier.

The projects share benchmark controls and acceptance principles, but keep their runtime configuration, authentication state, and model routing separate.

License

MIT