Give each agent one directory it owns outright, and nothing else. Name the shared files that everything touches, forbid them to every agent, and wire them up yourself once the agents are done. Send every question an agent has for you to one inbox rather than leaving it in whichever terminal it was asked in. Keep the machine inside a CPU and memory budget. And check what each agent reports before you repeat it, because a confident report and a correct one look the same.
I run several agents at once most days, across a handful of repositories, and I built a tool for it, Sentinel, once doing it by hand stopped scaling. Everything below is something that went wrong first.
Why do parallel agents step on each other?
Because each one sees the repository as if it were alone in it. Ask two agents to build two pages and both will decide the navigation needs a new link, and both will add it. Each edit is reasonable. Together they make a merge conflict, or worse, a quiet overwrite where one agent’s work disappears and nobody notices for a day. A polite sentence in the brief doesn’t prevent this. Ownership does.
How should you divide the work?
By directory, exclusively. Each agent owns one folder and may edit nothing outside it. The files every part of the system touches, such as the navigation, the global stylesheet and the lockfile, are named in the brief as forbidden, and the lead session joins them up afterwards. New styles go into a stylesheet scoped to that agent’s area, with a prefix nobody else uses.
Sentinel turns this from a promise into a claim. Before it edits, an agent claims the paths it will touch. An overlapping claim is refused and names the holder, so the second agent sends the first a question instead of editing. Claims are leases that lapse after thirty minutes without a word from the agent, so one that crashed doesn’t lock a folder for ever. A few paths are guarded outright, and only the lead may claim them.
Point each agent at the components it must reuse, by path, with a plain instruction not to write a second one. Agents are very willing to build a fresh version of something that already exists, and it always comes out nearly right, which is worse than obviously wrong.
Every collision I’ve had came from two agents doing sensible work in the same file.
What should an agent do when it gets stuck?
Ask, in one place. Every decision, credential or click in a third-party dashboard an agent needs from me goes into Sentinel as an ask. I see them in one window, with a notification for the ones that block. Before that, questions sat in whichever terminal I wasn’t looking at, and agents either waited for hours or guessed.
Tell them, too, to say what they could not find out rather than filling the gap with something plausible. A confident wrong answer costs more than a blank, because you act on it. And when an agent says the brief itself is wrong, read its evidence properly. One of mine contradicted three premises in its own brief and was right about all three.
How do you stop them overloading the machine?
Give the machine a budget, and tell every agent when it is over. Sentinel samples the Mac every five seconds. By default, CPU above 85% for a sustained minute, or memory above 85%, counts as a breach. When that happens every agent is told, and none should start a dev server, a build or a test run until it recovers. It never tells an agent to stop my own processes.
One trap is worth passing on. The first version also counted swap, and the machine was over budget all day: macOS keeps pages in swap long after the pressure that put them there has gone. The agent building the feature measured that before trusting its brief, and pushed back. Swap now counts only while the system reports memory pressure.
What breaks that you wouldn’t expect?
- A production build beside a running dev server. Next.js, for one, keeps both in the same folder, so a build replaces the files the dev server is serving and the page comes back as unstyled HTML. Agents should run the type checker directly and leave the build alone.
- Checks that walk the disk. Agents often work in git worktrees inside the repository. On one day, three of my checks failed because they found a worktree’s files and treated them as the real ones. A check should ask git what is in the tree.
- Reports taken mid-edit. Twice an agent told me a file failed its typecheck when it was clean: it had run the compiler while another edit was half written. I check before I repeat anything an agent tells me.
- Unfinished code reaching live data. An agent’s working copy once reached my real Sentinel store through a hook, minutes after a database migration was written and before it had been tested. Now only installed code ever touches the real store.
How many agents is too many?
More than you can review. The machine will take a fair number if its budget is watched, and the repository will take as many as there are clean divisions of ownership. The limit is you. Each agent ends by handing over work that has to be read, checked and joined up, and work you skim is work you will redo. I would rather run three agents whose output I read properly than eight I glance at.
Where should you start?
With two agents and a written list of who owns what. Name the shared files and keep them for yourself. Give every agent the same instruction to ask rather than guess, and to report what it could not determine. When the collisions stop, add a third. If you would rather have the tooling than keep the discipline by hand, Sentinel is free to anyone who joins my network.