Codex Lean

One agent by default. Premium reasoning only where failure is expensive.

Codex Lean is a small, project-scoped routing policy for Codex. It keeps routine work on GPT-5.6 Luna, escalates coherent difficult work deliberately, reserves Sol High for costly failure modes, and prevents recursive or overlapping agent teams.

It is designed to improve accepted work per credit without weakening review or testing.

Why it is lean

Codex Lean does not add another orchestrator, mandatory advisor, provider bridge, daemon, credential, or fixed multi-agent graph.

                         YOUR TASK
                            |
                    Luna High root
                    classifies risk
                            |
          +-----------------+-----------------+
          |                 |                 |
     routine work      deeper work       costly failure
       root owns      Luna XHigh owns      Sol High owns
          |                 |                 |
          +-----------------+-----------------+
                            |
                  frozen independent review

Most tasks stay in the root. Delegation is an exception with a measurable reason.

Routing ladder

Work	Model	Behavior
Routine deterministic work	Luna High root	no delegation
Non-trivial coherent implementation	Luna XHigh worker	one implementation owner
Financial, security, permissions, destructive data, migration, deployment, or concurrency risk	Sol High worker	fail closed if unavailable
Bounded exploration	Luna High explorer	read-only
Routine frozen review	Luna XHigh reviewer	independent and read-only
Critical frozen review	Sol High reviewer	independent and read-only

The project cap is two child threads with depth one. Every routed child receives a self-contained brief with fork_turns = "none". Children never create descendants.

Install

Add the marketplace and plugin:

codex plugin marketplace add HenkDz/Codex-Lean
codex plugin add codex-lean@codex-lean

Start a new Codex task, then run:

/codex-lean setup

Codex previews the project changes before creating them. Existing model defaults, repository governance, permissions, and unrelated configuration are preserved unless you explicitly approve a conflict.

Use

After setup, work normally. Repository guidance and custom-agent descriptions provide the routing policy.

Useful commands:

/codex-lean status
/codex-lean optimize this project
/codex-lean update
/codex-lean remove
/codex-lean no subagents — fix this isolated warning

Setup is project-scoped and version-controlled:

.codex/config.toml
.codex/agents/lean-explorer.toml
.codex/agents/lean-worker.toml
.codex/agents/critical-worker.toml
.codex/agents/lean-reviewer.toml
.codex/agents/critical-reviewer.toml
AGENTS.md

Efficiency principles

Optimize accepted-change cost, including retries and review corrections—not raw token count alone.
Do not pay an orchestration tax on a task one agent can finish.
Route by cost of error, not by file count or impressive model names.
Keep one implementation owner.
Use fresh child context instead of cloning the full conversation.
Freeze before review; any later edit invalidates the review.
Never select Max or Ultra automatically.
Never claim a child route worked unless runtime evidence confirms it.

Honest limitations

Subagents can increase raw token use even when cheaper models reduce weighted credits.
Custom-agent configuration does not prove which model a live child actually used.
Parent runtime permission choices can override a child sandbox request.
Model pricing, availability, identifiers, and Codex routing behavior can change.
A repository's stricter engineering or security rules always win.

Codex Lean fails closed when a critical route is unavailable. It never silently performs high-risk work with a cheaper inherited model.

Validate a configured project

The bundled checker is read-only:

python3 plugins/codex-lean/scripts/check_project.py /path/to/project

It validates the routing ladder, thread limits, role boundaries, and project marker. It explicitly does not claim live model identity.

Development

python3 -m unittest discover -s tests -v

Security

Codex Lean uses no network service, provider bridge, API key, or credential store. See SECURITY.md.

License

MIT

HenkDz/Codex-Lean

README