Running parallel agent sessions without them stepping on each other

· 7 min read

I usually have several coding-agent sessions running at once. Sometimes on different projects, often on the same repo: one session deep in a refactor, one writing docs, one investigating a bug. Nothing about an agent harness makes this safe by default. The two failure modes show up fast:

  1. Corruption: two sessions write the same state file and one clobbers the other.
  2. Collision: two sessions, blind to each other, pick up the same work or edit the same files, and you discover it at diff time.

These feel like one problem ("agents conflict") but they are structurally different, and in my memory system they got structurally different fixes. The corruption fix has no runtime component at all. The collision fix has no locks. This post is about both, and about the things I deliberately did not build.

Corruption: solved by construction, not coordination

Each of my agent sessions keeps working memory on disk: a scratchpad, a decision log, open questions. The naive layout - one set of files per project branch - dies immediately with two live sessions, and the classic answer is locking or serialized writes through a daemon.

The layout that needs neither: every session writes only to its own directory, keyed by its session id. Subagents inherit the id with a suffix, so even a session's own workers cannot collide with their parent. No two writers ever touch the same file, not because a lock stops them, but because no shared file exists. At session start, a materialize step folds all sessions' entries into one read-only merged view, so a new session still reads everything that happened on the branch - stamped as historical reference, because a snapshot is stale by definition.

There is exactly one exception, and it is load-bearing: a single current-task.md per branch, shared by every session, last writer wins. That file answers "what is this branch about right now", which is only useful because it is shared. The design rule that fell out: share nothing by default, and when you do share, share one small file whose whole point is being the single meeting place.

This solved corruption completely. It did nothing for collision - a session writing safely in its own directory can still cheerfully redo work another session finished an hour ago.

Collision: sessions need to see each other

The actual pain, once corruption was gone, was launching a second session into a repo blind. It did not know a first session existed, let alone what files it was touching. My fix is a presence layer: a machine-local registry of live sessions, maintained entirely by lifecycle hooks that were already firing on session start, tool use, and session end.

Each record carries the branch, the files the session has touched, an optional one-line intent, and a freshness timestamp. When a new session starts, it gets a block injected into its context:

3 other session(s) live on this branch right now - avoid editing the same files:
- 6679ade6 - touching channel.md, production-readiness.md (active 5m ago)
- 30b9890c - touching audit.rs, audit.test.ts (active 52m ago)
- c5e09075 - touching review-queue.md, CONTEXT.md (active 1h ago)

That is most of the feature. The dominant collision case was never two sessions racing for a file at the same millisecond; it was me starting session B without remembering what session A was doing. Awareness at launch time, plus an on-demand "who else is here" query the agent can run mid-session, covers almost all of it.

The part that took actual design care is trust. A presence registry is only useful if the agent can believe it: phantom peers - records of sessions that died without cleaning up - turn the block into noise the agent learns to ignore, and then the feature is worse than nothing. Session-end hooks are unreliable by nature (crashes, hard kills, dead batteries), so liveness is checked at read time against the OS: does the recorded pid exist, and does its process start-time match what the record captured? The second check matters more than it looks. Pids get reused; without the start-time match, a recycled pid makes a dead session read as alive forever, which is precisely the failure the layer exists to prevent.

No locks, on purpose

The instinctive design here is mutual exclusion: lock files a session is editing, deny the other session access. I rejected it, and the reasoning generalizes:

So the whole layer is advisory. It informs, it never blocks. Weeks in, I have not once wished for the lock.

I also rejected the heavier alternative: a durable task queue where every session formally claims a task before touching anything. Queues answer "what is the status of this work" - a real question, but a different one. For live collision avoidance a claimed task is simultaneously too coarse ("someone is on the refactor" does not tell you which file they are editing right now) and too much ceremony (every session pays a claim step to defend against a rare event). Presence is finer and free: the hooks fire anyway.

The human side: which session needs me

Coordination between sessions is half the story. The other half is coordinating me. With four sessions across three projects, the expensive question stops being "are the agents colliding" and becomes "which one is waiting on my input while I stare at a different terminal".

Presence records carry a state field for this: working or waiting. Turn boundaries drive it - submitting a prompt marks the session working, the agent finishing its turn marks it waiting. The subtlety is that tool activity alone cannot tell you this: a session that is thinking, or reading files, looks idle by every activity metric while genuinely busy. Only the turn boundary is truthful. A workbench view renders the sessions per project with a marker on whoever is waiting, and a backgrounded session going idle fires a notification.

The effect on throughput is larger than the collision fix. Parallel sessions were already safe; this made them worth it, because agent idle time - finished, waiting, unnoticed - was where the parallelism actually leaked.

What transfers

The specifics are mine, but the shapes are portable to any multi-session agent setup:

None of this needed a coordinator process, a message bus, or a database. It is a directory convention, a handful of JSON files in a cache directory, and hooks that were already firing. The boring infrastructure was the feature.