Coding agents

How to run a code migration across many repositories with coding agents

Capy team

Prove the migration in one pull request on one repository, then give each remaining repository its own agent and its own pull request against that repository's base branch. Write the change down once, with the commands that prove it, and fan out only after the pilot merges. In Capy a Captain does the fan-out: the project lists the repositories, the Captain starts one crew thread per repository, and each thread follows its pull request through CI and review until a person merges it.

Why one agent per repository

A migration across 40 repositories is 40 separate changes, each with its own CI, its own reviewers and its own release. When we split a large migration or audit across a crew, our Captains start one thread per repository or area of code that can land on its own, keep findings that touch the same code in one thread, and check other crews for overlap before briefing so two threads don't edit the same call sites from opposite directions. That lets a failing repository wait without blocking the rest, avoids running everything in sequence inside a single context window, and lets follow-ups return to the thread that built the pull request so context isn't lost.

The setup has five parts:

  • The spec: the exact change, the commands that prove it, and what to skip. Written once, read by every agent.
  • The pilot: one repository, migrated and merged, so the spec reflects what actually broke.
  • One agent per repository: makes the change, runs that repository's checks, and opens and follows one pull request.
  • A coordinator: starts the agents in batches, reads what each one reports, and asks you only about the exceptions.
  • A recurring check: finds code that still uses the old pattern after the migration, and fixes it.

Write the spec

The spec decides how much review each pull request needs. Include:

  • The change. A codemod, a search pattern with its replacement, or the before and after of one call site. "Upgrade to v5" leaves too much to guess.
  • The proof. The commands every repository must pass, such as the type check, the tests and the build. Our Captains treat a pull request as done only after reading four facts themselves at its current head commit: CI green, review finished with no open findings, mergeable with no conflicts, and the right base branch.
  • The order. Shared libraries migrate first, and the repositories that use them follow once the library's release is out. During a major framework upgrade, we landed prep pull requests first and learned to keep the window between verified and merged short, because letting a verified branch wait lets the base branch move underneath it and multiply conflicts.
  • The stop rules. What the agent does when the migration needs a design decision: stop, name the file, and report.

Every crew thread we start gets the same brief: the person's words verbatim, the file or component, the decision, what done means, what is out of scope, the standing rules and where to leave its report. We also include one fallback rule: if the code makes the brief wrong, pick the closest behavior that keeps the goal and say what you chose.

Run it in Capy

  1. Put the repositories in one project. A project can list hundreds of repositories. Mark the ones most threads never touch as lazy, and Capy clones them only when a thread needs one.
  2. Make the checks runnable. The project's environment has to install and test each repository, or the agents can't prove their changes.
  3. Create a Captain in that project and give it the spec in the first message. It saves the rules every crew thread follows in CREW.md in its Drive.
  4. Run the pilot. Ask for one crew thread on a small, representative repository. Review that pull request closely, merge it, and tell the Captain what to change in the rules.
  5. Fan out in batches. "Start one crew thread per repository on this list, ten at a time." Each crew thread opens its pull request against that repository's base branch, and a failing check or a review comment wakes the thread that owns the pull request.
  6. Track the batch. The Pull requests page filtered by Captain lists every pull request the crew opened. The Captain hears from each crew thread when it finishes a turn or needs something, and passes on only the decisions that are yours.
  7. Keep it migrated. An automation on a weekly schedule can search for the old pattern and open a pull request when it finds one.

What still needs a person

  • Merging. Capy never merges unless someone asks for that merge, or the repository's root AGENTS.md grants it. In our own crews, the real limit is asks waiting on one person, not threads running, and the first verified pull request that goes stale in the queue is the sign to slow down. We batch merge asks by issue, pin each merge to the verified head commit, and have the Captain re-read live state right before every irreversible step because another merge may have landed in between.
  • Decisions the spec didn't cover. Expect a long tail of repositories with a custom wrapper, an old test setup or code that contradicts the brief. When a thread hits a decision the brief didn't settle, our Captains bring it to the person with the choices written out instead of guessing.
  • Atomic changes. Pull requests in separate repositories merge separately, so a change that must land everywhere at once needs a compatibility step, such as supporting both versions for a release. One person or agent needs to own the order of everything that touches production, because other teams' merges land mid-change, stacked pull requests have to be retargeted after their base merges, and a dependency merging mid-plan can force a re-cut.
  • Capacity. Your plan caps how many cloud machines run at once, from 8 Large machines on Lite to 64 on Max. Plan limits has the numbers, though review and merge bandwidth usually runs out before machine memory does.

For a single repository on a schedule, such as routine version bumps, the nightly dependency update guide is the simpler setup. For how a coordinator runs a team's agents beyond one migration, see Orchestrating coding agents across a team.

Follow-up questions

Should I use a codemod tool or an agent?

Both. A codemod handles the mechanical part the same way everywhere. The agent runs it, fixes what it couldn't handle, runs the repository's checks and opens the pull request. Put the codemod command in the spec.

What if the repositories are in different projects?

A Captain's crew threads stay in the Captain's own project. Put the repositories in one project for the migration, or run one Captain per project.

Can the agents open the pull requests as drafts?

Yes. Add it to the spec, for example "open every pull request as a draft until its checks pass", and the Captain writes it into the crew's rules.

How do I stop the batch?

Tell the Captain, for example "stop starting new threads". To stop the ones already running, archive them, or ask the Captain to. An archived thread keeps its history, and its pull requests stay open on GitHub.