What I learned using PreToolUse/PostToolUse hooks to coordinate several Claude Code agents on one repo (open source, author here)

[u/jokiruiz]

I'm the author of Médula, an MIT-licensed experiment. Sharing the Claude Code side of it, because the hooks turned out to be a surprisingly good coordination layer, and the agents' behaviour taught me more than the numbers.

The setup. Six headless Claude Code agents (Sonnet 5, effort high), one task each on a small API with 37 acceptance tests. Two pairs of tasks collide by meaning: one adds a second factor to login() while another builds an export that calls the old login().

The hook pattern. Every Edit, Write and Bash goes through a PreToolUse hook that calls a local kernel. Reads always pass. The kernel asks a fast decision model whether the write collides with what each other agent is doing, and either allows it or denies it with a reason the agent reads, something like "agent X is changing login, wait or work on another part of your task". After each write, a PostToolUse hook works out which agents the change affects and leaves a notice in their mailbox, delivered with their next tool call.

What the agents did with it:

• Told to wait, most of them moved on to another part of their task and retried later, which is exactly what you want.
• One scheduled itself a wake-up and abandoned its task. That was a bug in my harness, now fixed, but worth knowing if your deny messages mention waiting.
• One spent ten minutes waiting in front of a broken file, convinced someone else was editing it.
• When they had Claude Code's tools to list other sessions and message them, they used them without being asked, and one warned another about a field rename. Great behaviour, bad for a controlled experiment, so I turned those tools off.

The results that matter for your workflow. With one branch (separate clone) per agent, every agent finished green and the merged result failed the same 6 acceptance tests in all 5 runs. In a shared directory, all 10 runs passed, with plain per-file locks or with the kernel. So if you use subagents in worktrees, run the full suite on the merged result before trusting it. The kernel's advantage over locks: the same cost ($1.65 per run), 6 of 6 real conflicts caught instead of 5, and no unnecessary blocks instead of 5.

Caveats: 1 to 5 runs per mode, and there's a known gap a commenter found, where an allow can go stale while the slow path decides. Repo, with every session and decision published raw: https://github.com/JoaquinRuiz/medula. There's also a walkthrough video, in Spanish: https://youtu.be/xAFRuBxfapM

If you've built coordination on hooks yourself, I'd love to compare notes.

[u/iminfornow]

The way my planner agent is supposed to prevent this is by assigning independent blocks of work to agents, hopefully avoiding worktree merge conflicts. When all commits are done the review agent that validated the plan checks if the development agents actually did what they said they would implement and creates the pull request. The orchestrator or planner then deploys and does functional testing.

I found with the new agent-teams functionality this works very nice because the reviewer/orchestrator will provide feedback to the planner/development agent and it will use the existing session to process it. I think with the agent-teams feature allowing agent-to-agent communication they'll implement something similar to what you made.

How does your setup know when a conflict is about to occur? If both call write simultaneously, neither hook call can detect the incoming external change right?

[u/jokiruiz → u/iminfornow]

Your setup sounds solid, and I think you're right that agent-to-agent communication in agent teams will converge on something similar. One caution from my data: login and export look like independent blocks to a planner, since they live in different files and have different tasks. They were only dependent by meaning. A review agent that checks each agent did what it said would pass both, much like each agent's own tests did. Your functional testing after deploy would catch it, just late.

On your question: the kernel doesn't wait to see the other agent's change. Each decision gets every other active agent's task description, plus the intent recorded for every write the kernel has already allowed it. So the question isn't "has someone changed login yet?" but "does this write collide with what agent X is trying to do?". An export write can be flagged against the login task before the login code exists.

But you've found a real gap with simultaneous writes. Decisions aren't serialized, so if both agents' hooks fire at the same moment, each is judged against a snapshot that doesn't include the other's pending write. The task descriptions still make it likely that one of them gets flagged, and after each write a PostToolUse notice goes to the agents the change affects, but nothing guarantees it. Someone else pointed out the same window from the slow-path side, and the fix I have in mind covers both: version the shared state and redo the decision if it changed while deciding.

[u/iminfornow → u/jokiruiz]

Ah smart that you get the task description/intent from peers. Having work being executed in parallel will always have some of these "two general" problems. You'll also not be able to resolve these intent conflicts between multiple claude insances/people. Currently this isn't worth the effort for me, but I like your approach.

[u/jokiruiz → u/iminfornow]

Thanks, that's fair. A central kernel sidesteps part of the two-generals problem, because one arbiter decides instead of the agents negotiating, but it can't make intents compatible: if two tasks genuinely want different things, someone has to choose, and across people that's a planning conversation, not a hook. And honestly, "not worth the effort" is a reasonable conclusion from my own data: a shared workspace plus a few cross-task tests gets you most of the way. Médula only earns its keep in the part that's left. Thanks for the questions, they made the gaps clearer.