Delegating Tasks to the Cloud

The Master Agent Pattern

For large-scale tasks, Codex uses a master/sub-agent architecture. Instead of doing everything sequentially, the primary CLI instance acts as a Project Manager that coordinates multiple specialized workers.

How Cloud Delegation Works

Here's the step-by-step workflow:

Step 1 — Provide a Large-Scale Prompt

Give Codex a high-level objective that would normally take hours or days:

# Large migration task
codex run "Migrate this React app from Webpack to Vite" --cloud

# Full refactoring
codex run "Convert all JavaScript files to TypeScript with strict mode" --cloud

# Comprehensive testing
codex run "Write unit tests for every module in the src/ directory" --cloud

Step 2 — Task Breakdown

The master agent analyzes your codebase and fragments the objective into smaller, independent sub-tasks. For example, a TypeScript migration might break down into:

Sub-tasks generated:
  1. Convert src/utils/*.js → TypeScript
  2. Convert src/hooks/*.js → TypeScript
  3. Convert src/components/Header.jsx → TSX
  4. Convert src/components/Footer.jsx → TSX
  5. Convert src/api/*.js → TypeScript
  6. Update tsconfig.json with strict settings
  7. Fix type errors in converted files
  ... (50+ tasks)

Step 3 — Concurrent Dispatch

Instead of working through tasks one by one, the master agent dispatches sub-tasks to multiple specialized cloud agents running concurrently. Each sub-agent:

• Gets a focused, well-defined task
• Runs in its own isolated Docker container
• Has access to the full codebase for context
• Works independently of other sub-agents

Step 4 — Monitor Progress

Watch the real-time dashboard from your local terminal:

codex cloud status

The dashboard shows live activity for all sub-agents:

☁️  Cloud Delegation Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Master Agent: "Migrate to TypeScript"
Sub-agents: 12 active, 38 completed, 5 queued
─────────────────────────────────────────
✅  agent-01: Convert utils/*.js          [DONE]
✅  agent-02: Convert hooks/*.js          [DONE]
🔄  agent-03: Convert Header.jsx          [WORKING]
🔄  agent-04: Convert Footer.jsx          [WORKING]
⏳  agent-05: Fix type errors             [QUEUED]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 5 — Result Assembly

Once all sub-agents complete, the master agent assembles and validates the combined results. It resolves any conflicts between sub-agent outputs and syncs everything back to your local workspace.

When to Use Cloud Delegation

• Framework migrations — Webpack → Vite, JS → TypeScript, React class → hooks
• Bulk refactoring — Renaming patterns across hundreds of files
• Test generation — Writing tests for an entire codebase at once
• Documentation — Generating JSDoc/TSDoc for all exported functions

What's Next

In the final episode, we'll dive into running tasks in parallel locally — batch processing, branch isolation, and intelligent auto-merging.