Multi-Agent Parallel Feature Work

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

• 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.

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 Codex App 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

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 App sidebar 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 by pressing Enter while Codex is running to inject new instructions. Press Tab to queue a follow-up 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 This Breaks

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 limit reached. Codex cleans up worktrees when you exceed 10 or when they are older than 4 days. For five-feature parallel work, you are using 5 worktrees immediately plus any existing ones. Archive threads you no longer need, and pin any worktree you want to keep beyond 4 days.

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.

What’s Next

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