Session Isolation: How We Let 10 Agents Edit Code Simultaneously

The Concurrency Problem

When you run 10 AI agents on the same repository, something has to keep them from stepping on each other. The naive answer — give each agent its own copy of the repo — works for two or three agents but collapses at scale. A 5GB monorepo with 10 clones is 50GB of disk. Clone time alone eats minutes per agent. And you still need to merge 10 divergent copies back together.

We needed something fundamentally different: a way to give each agent full read/write access to the entire codebase with zero setup cost, complete isolation from other agents, and efficient merging when they're done.

The answer is workspace overlays.

What Is a Workspace Overlay?

A workspace overlay is a lightweight, copy-on-write layer on top of a shared codebase snapshot. Think of it as a transparent sheet placed over a document — you can see everything underneath, and anything you write goes on the sheet, not the document.

Loading diagram...

Each agent's overlay starts empty. As the agent works:

• Reads check the overlay first, then fall through to the shared base. If the agent hasn't modified a file, it reads the original. Zero copy cost for unmodified files.
• Writes go to the overlay only. The base layer is never modified directly. Other agents can't see these changes.
• Deletes are recorded as tombstones in the overlay, so the file appears deleted to this agent but still exists for everyone else.

The result: every agent sees its own consistent view of the codebase — its own changes plus the unmodified base — without any coordination.

Why Not Just Use Git Branches?

Git branches seem like the obvious solution: one branch per agent, merge when done. Here's why that breaks down:

Concern	Git Branches	Workspace Overlays
Setup cost	Full clone: seconds to minutes, GBs of disk	Connect in < 50ms, zero disk on the agent side
Storage	N agents = N full copies	N agents = N thin overlays (only changed files)
Isolation	Complete but expensive	Complete and cheap
Same-file edits	Always a merge conflict (line-level)	Auto-merge if different symbols (AST-level)
Real-time awareness	None until merge time	WATCH notifications for symbol changes
Merge complexity	O(N) sequential merges, each potentially conflicting	Semantic merge in < 50ms per changeset
Cleanup	Delete branches, worktrees, stale refs	Session overlay is garbage-collected automatically

The key insight: Git branches provide isolation through duplication. Overlays provide isolation through indirection. Duplication is expensive and scales linearly. Indirection is cheap and scales to dozens of agents on one codebase.

How the Overlay Lifecycle Works

1. Agent Connects

When an agent calls CONNECT, the platform creates a new session with an empty overlay pinned to the current codebase version (say, v1847). This takes under 50 milliseconds. No files are copied.

2. Agent Reads and Writes

The agent works normally — reading files, understanding context, writing changes. Every read checks the overlay hash map first. Every write updates the overlay. The agent has no idea it's working on an overlay; from its perspective, it has a full, private copy of the repository.

3. Agent Submits

When the agent is done, it calls SUBMIT. The platform takes the overlay's changeset — the set of files that differ from the base — and prepares it for verification and merge.

If the base has moved since the agent connected (because another agent merged changes), the platform detects this and auto-rebases: it replays the overlay's changes on top of the new base. If the changes are structurally compatible, this happens silently. If there's a real conflict, the agent gets structured feedback.

4. Merge or Conflict

The platform's semantic merge engine compares the overlay's changes against the current base at the AST level. Two agents modifying different functions in the same file? Automatic merge. Two agents modifying the same function? Real conflict, reported with symbol-level precision.

5. Session Cleanup

After a successful merge, the overlay is discarded. For persistent sessions (agents that pause and resume), the overlay survives disconnection and is cleaned up when the session is explicitly closed or expires.

Copy-on-Write in Practice

The copy-on-write model keeps resource usage proportional to actual changes, not repository size:

• A 100,000-file repository where an agent modifies 15 files: the overlay stores 15 files, not 100,000.
• An agent that only reads files: the overlay is empty. Zero storage overhead.
• An agent that creates 50 new test files: the overlay stores 50 files. The base is untouched.

This is the same principle behind filesystem snapshots (ZFS, Btrfs) and container layers (Docker's overlay2). It's well-proven technology applied to a new domain.

Handling the Moving Base

The hardest part of concurrent editing isn't isolation — it's what happens when isolated workspaces need to reconverge. Here's the sequence when multiple agents finish at different times:

Loading diagram...

Agent B doesn't need to know that the base moved. The platform handles the rebase transparently. If B's changes are compatible with A's (different symbols), the merge succeeds automatically. If they conflict, B gets a structured notification with the exact symbols involved.

Scaling to 20+ Agents

We tested the overlay architecture with 20 concurrent agents on a single codebase:

• Connect time: < 50ms per agent (all 20 connected in under a second)
• Memory overhead: proportional to changed files only — not 20x the repo size
• Merge throughput: semantic merges at < 50ms each, with auto-rebase handling base movement
• Conflict rate: with 20 agents on a large codebase, fewer than 5% of merges hit true semantic conflicts — the rest auto-merged because the agents were working on different symbols

The bottleneck isn't the overlay system. It's the verification pipeline — running tests takes real time. But because verification only runs affected tests (not the full suite), even that stays under 30 seconds per submission.

When to Use Session Isolation

Session isolation makes the most impact when:

• Multiple agents work in parallel on the same repo — the primary use case
• Agents work on overlapping files — the AST-level merge eliminates false conflicts
• Repos are large — no need to clone GBs of data per agent
• Tasks are independent but touch shared code — validation across 50 endpoints, logging migration, test coverage expansion

It's less critical when you have a single agent working on a single task — though even then, the fast connect and submit cycle is faster than clone/branch/push/PR.

---

This is the second post in our series on agent-native development. Previously: Why AI Agents Break Your Codebase. Next: Semantic Merging vs Git Merge.