codex-delegator

Codex Delegator Skill

Full documentation:

• ROUTING_SYSTEM.md
• ENTRYPOINTS.md

Real-World Performance (Tested 2026-01-18)

When to Use Codex

Codex excels at:

Do NOT use for: Architecture decisions, security review, documentation-heavy tasks.

Delegation Methods

Method 1: MCP Tool (Recommended)

Use the delegate_to_model MCP tool for intelligent routing:

delegate_to_model(task: "Implement a binary search function in TypeScript")

The CompositeRouter automatically routes to Codex when:

• Task contains code generation keywords ("implement", "write", "create")
• Task is primarily code-focused (low reasoning complexity)
• Budget constraints favor Codex cost efficiency

Method 2: Direct CLI Execution

For explicit Codex invocation, use codex exec for non-interactive mode:

# Basic code generation (non-interactive)
codex exec "Implement a binary search function in TypeScript"

# Via nexus-agents CLI
nexus-agents orchestrate "Implement sorting algorithm" --cli=codex

# Explicit model selection (default is gpt-5.2-codex)
codex exec -m gpt-5.2-codex "Implement a debounce function"

# Full autonomous mode (dangerous - writes files)
codex exec --full-auto "Add error handling to all functions in utils.ts"

Important: Use codex exec NOT codex -p. The -p flag is for interactive sessions.

Method 3: Routing Audit

Check routing decisions before execution:

nexus-agents routing-audit "Implement authentication middleware" --format=json

Task Profiling

The router analyzes tasks using these signals:

Examples

Generate Unit Tests

delegate_to_model(task: "Write Jest tests for the UserService class covering:
- createUser with valid input
- createUser with invalid email
- getUserById with existing user
- getUserById with non-existent user")

Implement Feature

delegate_to_model(task: "Implement a rate limiter middleware for Express.js that:
- Uses sliding window algorithm
- Supports configurable limits per route
- Returns 429 status when limit exceeded")

Refactor Code

delegate_to_model(task: "Refactor the payment processing module to:
- Extract validation logic into separate functions
- Replace callbacks with async/await
- Add TypeScript types for all parameters")

Bulk Changes

delegate_to_model(task: "Add JSDoc comments to all exported functions in src/utils/")

Routing Decision Flow

Task Input
    |
    v
TaskAnalyzer (profile task)
    |
    v
BudgetRouter (filter by constraints)
    |
    v
TopsisRouter (rank: quality 50%, cost 30%, latency 20%)
    |
    v
LinUCBBandit (contextual learning)
    |
    v
Codex selected if: high codeGeneration + low reasoningComplexity

Codex Capabilities

Best Practices (From Real Testing)

1. Be explicit in prompts - Include "Just output the function/code, no explanation" for cleaner output
2. Batch related requests - Session overhead is ~900 tokens, batch similar generations
3. Validate generated code - Run tsc --noEmit on TypeScript before integration
4. Set appropriate timeouts - Use 90s timeout for complex generations
5. Handle ambiguity - Codex asks clarifying questions for ambiguous prompts (graceful)

Fallback Behavior

If Codex is unavailable:

1. Circuit breaker detects failure
2. Router falls back to Claude or Gemini
3. Task executes with alternative CLI
4. Outcome recorded for learning

Configuration

# nexus-agents.yaml
routing:
  enableTopsisRanking: true
  enableLinUCBSelection: true

  topsis:
    qualityWeight: 0.5
    costWeight: 0.3
    latencyWeight: 0.2

Debugging

# Check Codex availability
nexus-agents doctor

# View routing decision for task
nexus-agents routing-audit "task description" --verbose

# Show bandit learning stats
nexus-agents routing-audit "task" --bandit-stats

Anti-rationalization — Codex delegation

Red flags

• Direct adapter call bypassing UnifiedAdapterRegistry
• No timeout set on the codex call
• Codex used for tasks classified as research/documentation (better routed to Gemini)
• Repeated rate-limit errors with no failover

Verification checklist

• Routing decision made via CompositeRouter.route() — no direct adapter instantiation
• Timeout set appropriate to task complexity (see CLAUDE.md complexity tier table)
• Failure mode tested — fallback CLI fires on rate-limit / connection-error
• Outcome recorded for adaptive routing (per CLAUDE.md routing changes)