Large-Scale Refactoring with Worktrees
Your team decided to migrate from Express to Hono, move from callbacks to async/await in the legacy data layer, and rename every getUserById to follow the new findUser convention — all before the next major release. That is hundreds of files across dozens of modules. Doing it in one branch means a two-week code freeze. Doing it with Codex worktrees means parallel, incremental migration with tests running at every step.
What You’ll Walk Away With
Section titled “What You’ll Walk Away With”- A plan-first refactoring process that decomposes large changes into safe, parallel batches
- Worktree patterns for isolating refactoring work so your main branch stays deployable
- Prompts that ensure Codex runs tests after every refactoring step, catching regressions immediately
- A cloud delegation pattern for refactoring tasks that take longer than a local session
The Workflow
Section titled “The Workflow”Step 1: Plan the Refactoring in the IDE
Section titled “Step 1: Plan the Refactoring in the IDE”Use the IDE extension or Codex App in Local mode to create a detailed refactoring plan. The plan is critical — without it, parallel agents will make conflicting changes.
If the $plan skill is available, it will produce a structured plan with milestones. Review and adjust the plan before executing — this is where you catch issues like “the auth middleware is used by every route group, so it must migrate first.”
Step 2: Migrate Shared Infrastructure First
Section titled “Step 2: Migrate Shared Infrastructure First”Handle shared dependencies in Local mode so every subsequent worktree inherits the changes:
Implement Milestone 0 from the refactoring plan: migrate the shared middleware layer.
Specifically:- Install hono and @hono/node-server- Create src/middleware/hono/ versions of each Express middleware- Keep the Express versions working (both frameworks coexist temporarily)- Update the middleware barrel export to expose both- Run the full test suite to confirm nothing broke
Do NOT migrate any routes yet. Only shared infrastructure.Commit this to your feature branch. Every worktree created from this point forward will have both Express and Hono middleware available.
Step 3: Execute Batches in Parallel Worktrees
Section titled “Step 3: Execute Batches in Parallel Worktrees”Now launch a worktree thread for each route group. Each agent migrates its batch independently, and because they touch different files, the results merge cleanly.
Worktree 1: Auth Routes
Migrate all routes in src/routes/auth/ from Express to Hono:- Convert each route handler to Hono's handler signature- Replace Express middleware references with Hono equivalents from src/middleware/hono/- Update imports throughout- Update the corresponding tests in tests/routes/auth/- Run the auth route tests after migration. Fix any failures.- Run the full test suite to check for regressions.
Follow the migration pattern documented in the refactoring plan.Worktree 2: User Routes
Migrate all routes in src/routes/users/ from Express to Hono. Same approach as the auth migration -- convert handlers, swap middleware, update tests. Run the full test suite after migration.Worktree 3: Order Routes (same pattern, different directory)
Worktree 4: Billing Routes (same pattern, different directory)
Each worktree runs its own test suite. If a migration breaks tests, the agent fixes it within the worktree before you ever see the diff.
Step 4: Review and Merge Incrementally
Section titled “Step 4: Review and Merge Incrementally”As each worktree completes, review the diff in the App’s review pane. Look for:
- Import paths that were not fully updated
- Middleware that was missed
- Tests that were modified to pass rather than actually testing the new behavior
Use Create branch here on each worktree, push to the remote, and open a PR. This lets your team review each batch independently rather than facing a 500-file mega-PR.
Step 5: Delegate the Cleanup to Cloud
Section titled “Step 5: Delegate the Cleanup to Cloud”After all route groups are migrated, the cleanup phase (removing Express, deleting the compatibility layer, updating docs) can run in a cloud task:
From the CLI, submit this as a cloud task with multiple attempts to ensure thorough cleanup:
codex cloud exec --env my-env --attempts 2 "Perform post-Express-to-Hono migration cleanup..."When This Breaks
Section titled “When This Breaks”Parallel worktrees modify the same file. If two route groups share a utility file that needs updating, both worktrees will modify it independently. The second sync will conflict. Prevent this by identifying shared files in the planning phase and migrating them in Step 2 (the foundation step) before parallelizing.
Tests pass in the worktree but fail after merging. This usually means the test was running against the worktree’s state, which did not include changes from other worktrees. After merging each batch, always run the full test suite from your local checkout to catch integration issues.
Codex makes the test pass by weakening the assertion. This is a subtle failure: instead of fixing the code to match the test, Codex changes the test expectation. Include “do NOT weaken or remove existing test assertions. If a test fails, fix the implementation, not the test” in your constraints.
Worktree cleanup removes a batch you have not merged. If you take more than 4 days to review a batch (and have more than 10 worktrees), Codex may clean it up. Pin the thread or add the worktree to the sidebar to prevent cleanup. Codex saves a snapshot before deleting, so you can restore from the thread view if needed.
The refactoring plan misses a dependency. If the plan says “auth routes do not depend on user routes” but they actually share a session validation helper, parallel migration will produce inconsistent results. Verify the plan by asking Codex: “Check the dependency graph between these route groups. Are there any shared imports I missed?”