Multi-Agent Parallel Feature Work

Multi-agent parallel feature work coordinates several Codex agents, each running in its own worktree, to implement a set of features at once instead of one engineer working through them sequentially. Shared infrastructure such as middleware or a pagination utility is built first in Local mode so every worktree inherits it, then agents implement their assigned feature in parallel before a developer reviews, tests, and merges each result into the codebase.

Your quarterly planning meeting just ended. The roadmap has five features due in three weeks: notification preferences, billing dashboard, user export, admin audit log, and a public API. Each feature touches different parts of the codebase. Traditionally, your four-person team would work on them sequentially with some overlap. With Codex, a single developer can coordinate five parallel agents, each working in its own worktree, producing reviewed PRs for each feature simultaneously. You become the architect directing a team of agents.

What you’ll walk away with from multi-agent parallel development

• A coordination pattern for running 4-6 Codex agents in parallel without conflicts
• Prompts for decomposing a feature set into independent workstreams
• Techniques for managing shared dependencies across parallel worktrees
• A workflow for reviewing, testing, and merging results from multiple agents

The Workflow

Step 1: Decompose into Independent Workstreams

The key constraint for parallel agent work is independence. Two agents modifying the same file will create merge conflicts. Start by identifying what can run in parallel.

Tip

Copy-paste prompt for parallel work decomposition:

I need to implement these five features:
1. Notification preferences (new API endpoints, database table, settings page)
2. Billing dashboard (new queries, charts page, PDF export)
3. User data export (background job, download endpoint, email notification)
4. Admin audit log (middleware, admin panel page, log viewer)
5. Public API (versioned routes, API key auth, rate limiting, docs)

Analyze the codebase and identify:
1. Which files each feature needs to create (new files = no conflict risk)
2. Which existing files each feature needs to modify
3. Shared files that multiple features would touch (these are conflict risks)
4. The dependency order: which features depend on shared infrastructure

Propose a parallel execution plan:
- Phase 1: Shared infrastructure changes (sequential, in Local mode)
- Phase 2: Independent features (parallel, in Worktree mode)
- Phase 3: Integration testing (sequential, after all merges)

Step 2: Build Shared Infrastructure First

Codex’s analysis will identify shared dependencies — maybe all five features need a new middleware, or the audit log feature needs to intercept routes used by other features. Handle these in Local mode first.

Tip

Copy-paste prompt for the shared-infrastructure phase:

Implement the shared infrastructure needed before parallel feature work:

1. Add the audit logging middleware that wraps route handlers (features 4 and 5 need this)
2. Update the database connection pool configuration to handle increased query load
3. Add the background job queue system (features 3 and 2 need this for PDF export and data export)
4. Create the shared pagination utility (features 1, 2, and 5 all need paginated list endpoints)

Commit each piece as a separate commit on the feature/q1-infrastructure branch.
Run the full test suite after each commit.

Merge this to your base branch. Now every worktree created from this point has the shared infrastructure.

Step 3: Launch Parallel Agents

Open the ChatGPT desktop app in Codex mode and create five worktree threads, all based on the branch with shared infrastructure merged. Each thread gets a comprehensive prompt with clear boundaries.

Thread 1: Notification Preferences

Tip

Copy-paste prompt for a single parallel worktree thread:

Implement the notification preferences feature:

Files to CREATE (no conflicts):
- src/routes/notifications/preferences.ts
- src/services/notifications/preferences.ts
- src/lib/db/queries/notificationPreferences.ts
- src/lib/db/schema/notificationPreferences.ts
- src/pages/settings/notifications.tsx
- tests/unit/services/notificationPreferences.test.ts
- tests/integration/routes/notificationPreferences.test.ts
- drizzle/migrations/XXXX_notification_preferences.sql

Files to MODIFY (coordinate carefully):
- src/routes/index.ts (add route import -- add one line only)
- src/lib/db/schema/index.ts (add schema export -- add one line only)

Constraints:
- Use the shared pagination utility for list endpoints
- Follow existing patterns in src/routes/ for handler structure
- Run the full test suite after implementation

Thread 2: Billing Dashboard (same structure, different files)

Thread 3: User Data Export (same structure, different files)

Thread 4: Admin Audit Log (same structure, different files)

Thread 5: Public API (same structure, different files)

Caution

The critical detail is the “Files to MODIFY” section. When multiple agents each add one line to the same barrel export file, merging will require manual conflict resolution. Minimize shared file modifications by being explicit about exactly what each agent should add.

Step 4: Monitor and Steer

With five threads running, the Codex-mode sidebar in the ChatGPT desktop app becomes your command center. Each thread shows its status: running, waiting for approval, or complete.

While agents work:

• Check progress by clicking into each thread. The conversation history shows what Codex has done and what it is working on.
• Leave inline comments if you spot an issue in the review pane. Then send a message: “Address the inline comments.”
• Send mid-task guidance through the composer (same in the CLI and the App): press Enter while Codex is running to inject new instructions into the current turn, or press Tab to queue a follow-up prompt for the next turn.
• Use the integrated terminal (Cmd + J) to verify changes in each worktree independently.

Step 5: Review, Test, and Merge

As each thread completes, follow this process:

1. Review the diff in the review pane. Focus on business logic, not formatting.
2. Run /review in the thread to get a second opinion from the reviewer model.
3. Create a branch with Create branch here on the worktree.
4. Push and open a PR directly from the App.
5. Request @codex review on the GitHub PR for team-visible review comments.

Merge order matters. Merge features with the fewest shared file modifications first. For the barrel export conflicts, resolve manually:

git checkout feature/notification-preferences
git merge feature/billing-dashboard
# Resolve conflict in src/routes/index.ts (add both import lines)
git add src/routes/index.ts
git commit -m "Merge billing dashboard into notification preferences branch"

After merging all five feature branches, run the full test suite once more to catch any integration issues.

Scaling with Cloud Tasks

For features that require longer execution (complex business logic, extensive testing), delegate to cloud tasks instead of local worktrees. Each cloud task runs independently in its own container.

# Launch three features as cloud tasks in parallel
codex cloud exec --env my-env "Implement the billing dashboard feature..." &
codex cloud exec --env my-env "Implement the user data export feature..." &
codex cloud exec --env my-env "Implement the public API feature..." &

Each task produces a diff and optional PR. Use --attempts 2 for features where quality matters more than speed — Codex generates two solutions and you pick the better one.

When multi-agent parallel development breaks down

Merge conflicts in shared files. Despite careful planning, some conflicts are inevitable. The most common: import barrel files, middleware registration, database schema exports. Minimize by telling each agent to add only one or two lines to shared files, and resolve conflicts during the merge phase.

One agent’s implementation is incompatible with another’s. Agent 1 builds the notification service expecting a specific event format; Agent 5 builds the public API emitting a different format. Prevent this by defining shared interfaces in the infrastructure phase. Include “use the EventPayload interface defined in src/types/events.ts” in both agents’ prompts.

Worktree retention reached. ChatGPT desktop keeps the 15 most recent Codex-managed worktrees by default. Five parallel features consume five slots immediately; adjust the retention limit or promote important worktrees to permanent projects.

Local machine runs out of resources. Five worktrees, each with its own node_modules and potentially running processes, can exhaust CPU, memory, or disk. Use cloud tasks for the heaviest features, and stagger local worktree starts so they are not all building dependencies simultaneously.

Tests pass individually but fail together. Each worktree tests in isolation. After merging, tests may fail due to interactions between features (port conflicts, database table conflicts in tests, shared state). Include an explicit integration testing phase after all merges.

Where to go next with multi-agent coordination

Codebase Modernization at Scale Apply parallel agent patterns to modernize entire codebases

Slack and Linear Integrations Coordinate parallel work with your team through Slack and Linear