Cli Codex

Codex CLI Orchestrator - Cross-AI Task Delegation

> CRITICAL — SELF-INVOCATION PROHIBITED > > This skill dispatches to the OpenAI CLI binary (codex). If the agent currently reading this skill is itself running inside Codex (detection signals listed in §2), the skill MUST refuse to load and return the documented error message instead of generating any codex invocation. > > A running CLI skill never dispatches itself. The cli-X skills are for cross-AI delegation only — never self-invocation.

Orchestrate OpenAI's Codex CLI for tasks that benefit from a second AI perspective, real-time web search, deep codebase analysis, built-in code review workflows, or parallel code generation.

Core Principle: Use Codex for what it does best. Delegate, validate, integrate. The calling AI stays the conductor.

---

1. WHEN TO USE

Activation Triggers

• Cross-AI Validation — code review second perspective, security audit alternative analysis, bug detection, /review diff-aware workflow.
• Web Research — current internet info via the top-level --search flag (codex --search exec …), latest library versions, API changes, community solutions.
• Codebase Architecture Analysis — onboarding to unfamiliar codebases, cross-file dependency mapping, architecture docs from code.
• Parallel Task Processing — offloading generation, simultaneous code generations, background docs/test generation.
• Agent-Delegated Tasks — specialized profile matches (.codex/agents/*.toml), session management (resume, fork), multi-strategy planning.
• Specialized Generation — explicit Codex requests, test suite generation, code translation, batch docs (JSDoc, README, API), visual input via --image/-i.

When NOT to Use

• You ARE Codex already. If your runtime is Codex (detection signal: $CODEX_SESSION_ID or any CODEX_* env var set, codex in process ancestry, or ~/.codex/state//lock present), this skill refuses to load. Self-invocation creates a circular dispatch loop and burns tokens for no value.
• Simple, quick tasks where CLI overhead is not worth it, or tasks needing an immediate response (rate limits may delay).
• Context already loaded and understood by the current agent.
• Interactive refinement requiring the full-screen TUI (use codex directly instead).
• Tasks where Codex CLI is not installed.

---

2. SMART ROUTING

Prerequisite Detection

# Verify Codex CLI is available before routing
command -v codex || echo "Not installed. Run: npm i -g @openai/codex"

Self-Invocation Guard

def detect_self_invocation():
    """Returns a non-None signal when the orchestrator is already running inside Codex."""
    # Layer 1: env var lookup — Codex sets CODEX_SESSION_ID and CODEX_* vars
    for key in os.environ:
        if key == 'CODEX_SESSION_ID' or key.startswith('CODEX_'):
            return ('env', key)
    # Layer 2: process ancestry — codex in parent tree
    try:
        ancestry = subprocess.check_output(['ps', '-o', 'command=', '-p', str(os.getppid())]).decode()
        if '/codex' in ancestry or 'codex ' in ancestry:
            return ('ancestry', 'codex')
    except subprocess.SubprocessError:
        pass
    # Layer 3: state lock-file probe
    state_dir = os.path.expanduser('~/.codex/state')
    if os.path.isdir(state_dir):
        for entry in os.listdir(state_dir):
            if os.path.exists(os.path.join(state_dir, entry, 'lock')):
                return ('lockfile', entry)
    return None

if detect_self_invocation():
    refuse(
        "Self-invocation refused: this agent is already running inside Codex. "
        "Use a sibling cli-* skill or a fresh shell session in a different runtime to dispatch a different model."
    )

Resource Loading Levels

| Level | When to Load | Resources | | ----------- | ----------------------- | ------------------------------ | | ALWAYS | Every skill invocation | references/cli-reference.md, assets/prompt-quality-card.md | | CONDITIONAL | If intent signals match | Intent-mapped reference docs | | ON_DEMAND | Only on explicit request| Extended templates and patterns |

Smart Router

Provider-specific dictionaries (used by the shared helper functions in [system-spec-kit/references/cli/shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md)):

INTENT_SIGNALS = {
    "GENERATION":        {"weight": 4, "keywords": ["generate", "create", "build", "write code", "codex create"]},
    "REVIEW":            {"weight": 4, "keywords": ["review", "audit", "security", "bug", "second opinion", "cross-validate", "/review"]},
    "RESEARCH":          {"weight": 4, "keywords": ["search", "latest", "current", "what's new", "web research", "--search", "browse"]},
    "ARCHITECTURE":      {"weight": 3, "keywords": ["architecture", "codebase", "investigate", "dependencies", "analyze project"]},
    "AGENT_DELEGATION":  {"weight": 4, "keywords": ["delegate", "agent", "background", "parallel", "offload", "codex agent"]},
    "TEMPLATES":         {"weight": 3, "keywords": ["template", "prompt", "how to ask", "codex prompt"]},
    "PATTERNS":          {"weight": 3, "keywords": ["pattern", "workflow", "orchestrate", "session", "resume", "fork"]},
    "HOOKS":             {"weight": 4, "keywords": ["hook", "hooks", "advisor brief", "startup context", "userpromptsubmit", "sessionstart", "codex_hooks"]},
    # WHY: DESIGN is an intent signal only. The durable sk-design-md-generator loading contract lives in the
    # always-fires Design Standards Loading rule and the dispatch manifest; RESOURCE_MAP stays
    # limited to same-skill markdown paths.
    "DESIGN":            {"weight": 4, "keywords": ["sk-design-md-generator", "extract design system", "generate design.md", "style reference", "design tokens", "css extraction", "tokens.json"]},
}

RESOURCE_MAP = {
    "GENERATION":        ["references/cli-reference.md", "assets/prompt-templates.md"],
    "REVIEW":            ["references/integration-patterns.md", "references/agent-delegation.md"],
    "RESEARCH":          ["references/codex-tools.md", "assets/prompt-templates.md"],
    "ARCHITECTURE":      ["references/codex-tools.md", "references/agent-delegation.md"],
    "AGENT_DELEGATION":  ["references/agent-delegation.md", "references/integration-patterns.md"],
    "TEMPLATES":         ["assets/prompt-templates.md", "references/cli-reference.md"],
    "PATTERNS":          ["references/integration-patterns.md", "references/cli-reference.md"],
    "HOOKS":             ["references/hook-contract.md", "references/cli-reference.md"],
}

LOADING_LEVELS = {
    "ALWAYS": ["references/cli-reference.md", "assets/prompt-quality-card.md"],
    "ON_DEMAND_KEYWORDS": ["full reference", "all templates", "deep dive", "complete guide", "codex agent", "codex prompt", "web research", "review command", "fork session", "hook contract"],
    "ON_DEMAND": ["references/codex-tools.md", "assets/prompt-templates.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is the user asking about Codex CLI specifically?",
    "Does the task benefit from a second AI perspective?",
    "Is real-time web information needed (--search)?",
    "Would codebase-wide analysis or /review workflow help?",
]

Call sequence (using shared helpers from shared-smart-router.md):

1. discover_markdown_resources() — recursively enumerate current .md files under existing references/ and assets/ folders at routing time.
2. _guard_in_skill() + load_if_available() — sandbox paths to this skill, reject non-markdown loads, skip missing files, and suppress duplicates.
3. score_intents(task) and select_intents(scores, ambiguity_delta=1.0) — preserve provider-specific weighted intent scoring and top-2 ambiguity handling.
4. get_routing_key(task, intents) — derive the provider routing key from task/provider context, then fall back to codex.
5. ALWAYS-load LOADING_LEVELS["ALWAYS"], then return UNKNOWN_FALLBACK with UNKNOWN_FALLBACK_CHECKLIST when max score is 0.
6. CONDITIONAL-load RESOURCE_MAP[intent], ON_DEMAND-load keyword matches, and return a notice when no provider-specific knowledge base is available beyond always-load resources.

The route_codex_resources(task) function body lives in [shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md) — substitute ` = codex`.

---

3. HOW IT WORKS

Prerequisites

Install with npm i -g @openai/codex (or brew install --cask codex). cli-codex authenticates through ChatGPT OAuth only — run codex login and complete the browser flow (requires a ChatGPT Plus/Pro/Business/Edu/Enterprise account). It does not use an OpenAI API key. Full install, auth, flag, sandbox, session, and troubleshooting tables live in the ALWAYS-loaded [cli-reference.md](./references/cli-reference.md) — this section keeps only the routing decisions and dispatch-critical gotchas.

Execution Ownership

This packet owns user-facing routing, the command -v codex availability probe, prompt construction, and the self-invocation guard. Actual process construction and execution delegate to the already-shipped deep-loop runtime at ../../system-deep-loop/runtime/scripts/fanout-run.cjs, using executor kind cli-codex.

The runtime is the single Codex execution adapter. Do not add a packet-local wrapper, command builder, or spawn path. Direct codex exec snippets below are operator reference and manual-testing examples; orchestrated dispatches use the shared runtime.

Provider Auth Pre-Flight (ChatGPT OAuth)

MANDATORY before any first dispatch in a session. cli-codex authenticates through ChatGPT OAuth only. If codex login has not been completed on this machine, a dispatch fails with 401 Unauthorized or not authenticated mid-round-trip. Run this check once per session, cache the result, and re-run it only if a dispatch fails with an auth error.

# One-shot pre-flight: capture ChatGPT OAuth status for routing
CODEX_AUTH=$(codex login status 2>&1)
echo "$CODEX_AUTH" | grep -qi "logged in\|chatgpt-oauth" && CODEX_OAUTH_OK=1 || CODEX_OAUTH_OK=0

Decision tree (apply in order — first match wins):

| State | CODEXOAUTHOK | Action | |-------|----------------|--------| | OAuth ready | 1 | Proceed with codex exec --model gpt-5.5 -c model_reasoning_effort="medium" -c service_tier="fast" | | Not logged in | 0 | ASK user to run codex login — surface the command, do NOT dispatch. Never substitute an API key or a different model. |

User prompt template — not logged in:

Codex is not authenticated on this machine. cli-codex uses ChatGPT OAuth only.
Run `codex login` (browser flow; requires a ChatGPT Plus/Pro/Business/Edu/Enterprise account),
then confirm when login finishes — the skill will retry the original dispatch.

Error-recovery contract. If a dispatch returns an auth error after pre-flight passed (OAuth expired or revoked), invalidate the cache, rerun codex login, and re-check before retrying. Never substitute a model the user didn't approve.

Default Invocation (Skill Default)

Default model + effort + tier: gpt-5.5 · medium reasoning · fast service tier. Balances speed, cost, and quality for the typical delegation.

codex exec \
  --model gpt-5.5 \
  -c model_reasoning_effort="medium" \
  -c service_tier="fast" \
  -c approval_policy=never \
  --sandbox workspace-write \
  ""

User override (honor explicit user phrasing verbatim):

| User says | Resolve to | |-----------|------------| | (nothing specified) | --model gpt-5.5 -c model_reasoning_effort="medium" -c service_tier="fast" | | "Use gpt 5.5 high fast" | --model gpt-5.5 -c model_reasoning_effort="high" -c service_tier="fast" | | "Use gpt 5.5 low" | --model gpt-5.5 -c model_reasoning_effort="low" -c service_tier="fast" (fast stays unless user drops it) | | "Use gpt 5.5 xhigh" | --model gpt-5.5 -c model_reasoning_effort="xhigh" -c service_tier="fast" | | "Use gpt 5.6 luna max" | --model gpt-5.6-luna -c model_reasoning_effort="max" -c service_tier="fast" | | "Use gpt 5.6 terra high" | --model gpt-5.6-terra -c model_reasoning_effort="high" -c service_tier="fast" | | "Use gpt 5.6 sol ultra" | --model gpt-5.6-sol -c model_reasoning_effort="ultra" -c service_tier="fast" |

Honor whichever dimensions the user names. Model stays on gpt-5.5 and service tier stays on fast unless the user explicitly names a different model or tier; keep the reasoning effort within the chosen model's ceiling (see Model Selection below and the roster in [references/providers-and-models.md](references/providers-and-models.md)).

Model Selection

gpt-5.5 at medium on the fast service tier (-c service_tier="fast") is the skill default for cross-AI delegation. Alternates: gpt-5.6-luna / gpt-5.6-terra (≤ max), gpt-5.6-sol (≤ ultra) — full roster, per-model effort ceilings, and the 8-level effort ladder in [references/providers-and-models.md](references/providers-and-models.md). Set effort with -c model_reasoning_effort="" (there is no --reasoning-effort flag).

Selection Strategy: default gpt-5.5 medium; raise to high / xhigh for architecture, security, and complex planning; escalate the model when the task wants reasoning past xhigh; drop to low / minimal for trivial lookups. Per-task rationale table: [cli-reference.md](./references/cli-reference.md) §5.

Codex Agent Delegation

The calling AI is the conductor; Codex profiles in $CODEX_HOME/.config.toml shape HOW Codex processes the task (sandbox, reasoning). Route with -p when the task matches a specialization. Full roster and invocation patterns: [agent-delegation.md](./references/agent-delegation.md).

| Task Type | Profile | |-----------|---------| | Code review / security audit | review | | Architecture exploration | context | | Technical research | research (+ top-level --search) | | Documentation generation | write | | Fresh-perspective debugging | debug | | Multi-strategy planning | ai-council |

Git diff review uses the built-in subcommand (no -p): codex exec review "..." --commit HEAD. Profiles may override model, model_reasoning_effort, sandbox_mode, approval_policy. The .codex/agents/*.toml files define personas for the interactive multi-agent TUI, NOT the -p flag.

Dispatch-Critical Gotchas

The full flag glossary, sandbox modes, unique capabilities (/review, --search, codex mcp, session resume/fork, --image, codex cloud), essential command examples, and troubleshooting table are in the ALWAYS-loaded [cli-reference.md](./references/cli-reference.md). Four gotchas that silently break a dispatch and must be honored at routing time:

• codex exec defaults to --sandbox read-only — file-modification tasks silently no-op (the agent plans changes but cannot write them). Pass --sandbox workspace-write; for headless no-prompt execution use top-level -a never before exec or -c approval_policy=never.
• --search is a top-level flag, not an exec flag — enable live web search as codex --search exec … (it precedes the subcommand). On codex ≥ 0.144 codex exec --search hard-fails with unexpected argument '--search' (older 0.125 builds accepted it), so treat any exec … --search example as stale. Without it, codex exec has no web access and answers from training data only — every dispatch needing live data (latest versions, repo facts, advisories) MUST use codex --search exec ….
• Always pass -c service_tier="fast" explicitly — this routes through the fast tier instead of whatever the caller's ~/.codex/config.toml defaults to. Explicit means reproducible regardless of who runs it.
• No --reasoning-effort, --reasoning, or --quiet flag exists — set effort with -c model_reasoning_effort=""; capture the last messa

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

Install and usage instructions live in the source repository linked above.