Codex CLI + IDE — Cost-Efficient Multi-Model Setup

Quick recovery guide · Based on the working Codex CLI 0.160.0 setup discussed and tested. Commands and model availability may change in future releases. The objective is to reduce subscription usage per successfully completed task, not to maximize delegation.

At a glance

Cost-first rule: Prefer a single agent. Subagents are optional and may increase overall usage. Global instructions can recommend routing but do not automatically change the parent model.

1. Quick command reference

2. Files and paths

3. Back up and inspect before editing

Run in Mac Terminal:

cp ~/.codex/config.toml ~/.codex/config.toml.backup
cat ~/.codex/config.toml
ls -la ~/.codex/*.config.toml
ls -la ~/.codex/agents/
cat ~/.codex/AGENTS.md

If a file or directory doesn't exist yet, an error from ls or cat is harmless. Never share API keys, tokens, or private environment values. Preserve existing notifications, project trust, plugins, MCP servers, desktop settings, memories, and hooks.

4. Configure default model and profiles

Edit the main config:

nano ~/.codex/config.toml

Set or update these lines near the top without replacing the rest of the file:

model = "gpt-6-luna"
model_reasoning_effort = "low"
plan_mode_reasoning_effort = "low"

Create the three profile files (these commands overwrite only these named profile files):

mkdir -p ~/.codex

cat > ~/.codex/light.config.toml <<'EOF'
model = "gpt-6-luna"
model_reasoning_effort = "low"
EOF

cat > ~/.codex/standard.config.toml <<'EOF'
model = "gpt-6.1-sol"
model_reasoning_effort = "low"
EOF

cat > ~/.codex/deep.config.toml <<'EOF'
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
EOF

Launch codex --profile light and check /status. In version 0.160.0, the --profile option may display an embedded-mode warning; this was harmless in your tested setup. Profile files are separate ~/.codex/<name>.config.toml files in this version.

5. Specialized subagents (optional)

You confirmed a real Light-agent delegation test worked. Recreate the agents with these commands (they overwrite only the named files):

mkdir -p ~/.codex/agents

cat > ~/.codex/agents/light.toml <<'EOF'
name = "light"
description = "Simple UI, CRUD, docs, isolated fixes."
model = "gpt-6-luna"
model_reasoning_effort = "low"
developer_instructions = """
Make small, focused changes. Follow existing patterns.
Run relevant checks. Avoid unrelated refactoring.
"""
EOF

cat > ~/.codex/agents/standard.toml <<'EOF'
name = "standard"
description = "Features, APIs, moderate debugging."
model = "gpt-6.1-sol"
model_reasoning_effort = "low"
developer_instructions = """
Implement moderate features. Follow project conventions.
Run tests, lint, and typecheck where available.
"""
EOF

cat > ~/.codex/agents/deep.toml <<'EOF'
name = "deep"
description = "Architecture, security, payments, complex bugs."
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
developer_instructions = """
Prioritize correctness, security, and data integrity.
Review edge cases. Request approval for destructive work.
"""
EOF

Troubleshooting: The first agent files were rejected because developer_instructions was missing. Keep that field in each definition. Subagents do not automatically change the parent model, and using two agents can increase usage.

6. Global routing instructions

Edit ~/.codex/AGENTS.md (global for all repositories):

nano ~/.codex/AGENTS.md

Append or reconcile this with any existing instructions:

## Cost-first Codex workflow

- Minimize subscription usage per successfully completed task.
- Prefer one agent; do not delegate merely to switch models.
- LIGHT: Luna Low for UI, docs, isolated fixes.
- MODERATE: Luna Medium if available; otherwise a suitable supported model.
- COMPLEX: Sol Low for significant features and debugging.
- CRITICAL: Sol High for auth, payments, settlements,
  migrations, concurrency, and security.
- If the current model is insufficient, recommend switching.
- Delegate only for independent or specialized work when benefits
  outweigh additional usage.
- Inspect only relevant files; avoid duplicate exploration.
- Verify with existing lint, typecheck, tests, and diff.
- Attempt one targeted correction, then escalate if needed.
- Never weaken tests or run destructive operations without approval.
- Report actual parent model, spawned agents, checks, and risks.
- Mark unverified model information clearly.

Use <repo>/AGENTS.md for project-specific conventions and business rules. Global instructions guide behavior but do not guarantee automatic parent-model switching.

7. How to identify the agent actually used

An agent can correctly classify a task without spawning a subagent. Profile sessions in embedded mode may not appear in the shared-daemon session browser.

Read-only delegation test: Ask Codex to actually spawn the Light agent to inspect package.json, summarize verification scripts, and change no files.

8. Verify each implementation

Run from the repository root:

git status --short
git diff --check
git diff

# Run only scripts present in package.json:
npm run typecheck
npm run lint
npm test

Different repositories may use different script names or test runners. Passing checks does not eliminate the need for review on sensitive changes.

9. Escalation policy

Important: Luna parent → Sol subagent → Luna review may use more allowance than a single Sol session. Subscription limits do not have a universal fixed per-task token exchange rate.

10. Troubleshooting and recovery

Restore the base configuration only:

cp ~/.codex/config.toml.backup ~/.codex/config.toml
codex doctor

This does not restore profiles, agents, or AGENTS.md. Back those up separately before major changes.

11. New Mac / reinstall checklist

• Install Codex and sign in with your subscription.
• Check codex --version and codex --help.
• Back up the existing ~/.codex/config.toml.
• Restore Light, Standard, and Deep profile files.
• Restore agent files, including developer_instructions.
• Restore global ~/.codex/AGENTS.md.
• Confirm codex features list shows multi_agent enabled.
• Launch codex --profile light and check /status.
• Run a read-only delegation test if needed.
• Monitor usage over several real tasks.

12. Daily workflow

1. Small changes: Luna Low → direct implementation → verify.
2. Moderate changes: Luna Medium if available, or Sol Low when necessary.
3. High-risk changes: Start Sol High directly.
4. Subagents: Only when independent work or specialized isolation justifies overhead.
5. Weekly: Compare completed tasks, retries, escalations, and subscription usage with your previous Sol-only workflow.

Version note: Based on Codex CLI 0.160.0 and the configuration shared in this conversation. Re-check model IDs, CLI syntax, agent schema, and subscription rules after updates.