How to Run Multiple Claude Code Agents at Once (Without Them Stepping on Each Other)

Can two Claude Code agents really work at the same time?

Yes, and the file-collision worry is solved in one move: separate git worktrees (or separate clones). Each long-running agent gets its own working tree on its own branch — git worktree add ../repo-agent-b branch-b — and merges flow through git exactly as they would for two human developers. No coordination needed, no "please don't touch src/" honor system.

If two agents must share one working tree, it can work when their file sets genuinely never overlap — but declare the boundary in writing (in the repo's CLAUDE.md), and beware the shared git index: a plain git commit from one agent can sweep up files the other agent staged. Commit with explicit pathspecs. When in doubt, use worktrees.

So "simultaneous" is easy. The harder question is what happens between sessions — and that's where most setups quietly fall apart.

If file conflicts aren't the problem, what is?

• Amnesia. Agents don't share memory. Session B has no idea what session A shipped, half-finished, or decided an hour ago. Without a written handoff, every session starts cold and re-derives — or re-does — the work.
• Silent claims. An agent reports "done" and times out, but the artifact never landed on disk. The next agent builds on work that doesn't exist. Hallucinated progress compounds unless verification is a norm.
• No mailbox. Agent A discovers something Agent B needs. Pasting it into your chat with B does nothing durable — B's next session never sees it. Messages need a place on disk, not in a conversation.
• Coordination tax. If the human has to route every handoff by hand, the fleet is slower than one agent. Coordination has to be something agents do to each other, by protocol.

Every one of these is a memory problem. The fix is to move coordination out of anyone's head — human or model — and onto disk.

What is an agent memory system (GAM / LAM)?

A shared folder with rules. No server, no database, no orchestration framework — which is exactly why it's durable. We use two names for the same layout: LAM (Local Agent Memory) is the bus as a plain folder on one machine, outside every git repo, shared by every agent on that machine. GAM (Global Agent Memory) is the identical layout on shared storage — a network drive or a NAS reached over a mesh VPN like Tailscale — so agents on different machines read and write the same bus.

In production at TKC Group that means roughly a dozen Claude Code agents across a MacBook Pro and a Mac mini, all mounted to one NAS over Tailscale, each keeping a local mirror that buffers when the network drops and syncs back up when it returns. The bus itself has exactly three moving parts.

How do shards, fridges, and the thread lifecycle work?

1. Shards — each agent's heartbeat. One append-only markdown file per agent. At every session close, the agent prepends a dated block: what shipped, what's open, what's blocked. Newest first, history never rewritten. The next session — any agent, any model — reads the top of the file and knows exactly where things stand.
2. Fridges — messages between agents. One inbox folder per agent. To tell another agent something, you write a small file into its fridge with who/when/priority frontmatter and a unique timestamped filename, so simultaneous writers can never collide. Handled messages move to a processed folder. Nothing important ever lives only in a chat.
3. The thread lifecycle — when coordination happens. Two commands: /thread-start reads your shard and sweeps your fridge before any work begins (the inhale); /thread-close writes your heartbeat and drops your messages before the session ends (the exhale). Agents don't coordinate continuously — they coordinate at these two moments, which is why the discipline holds even with a dozen agents running.

On top of that lifecycle you can layer the always-on patterns: recurring loops that run start-work-close on a budget for hours, and monitors that watch an inbox for a reply after you've asked another agent to do something. But those are accelerants. The bus is the engine.

What rules keep a fleet of agents honest?

The folder is trivial; the rules are the system. The short version of ours — each one earned the hard way:

• Shards are append-only — history never gets rewritten or "cleaned up." The log is your recovery infrastructure.
• Fridge filenames carry timestamp + author + topic, so concurrent writers can't overwrite each other.
• No secrets on the bus. It's a plaintext folder — keys and tokens are referenced by name, never pasted.
• The bus lives outside every git repo, so it can never be accidentally committed or force-pushed away.
• Verify other agents' claims against the filesystem. If a heartbeat says "shipped" but the commit isn't there, treat it as a timeout hallucination and re-check before building on it.
• A sent message isn't done until the reply lands — watch your inbox or hand the open loop to your next session.
• Destructive and outward-facing actions — deploys, deletes, publishing — stay gated on a human, no matter how autonomous the agent.

How do I set this up on my own machine?

In one conversation. Both companion files are downloadable at the top of this page. The PDF is the visual field guide — the architecture, the three primitives, the rules, and the scaling ladder from a single laptop to a NAS-backed fleet. The markdown file is the interesting one: it's written to your agent, not to you. Download it, open Claude Code, and say: "Read agent-memory-setup.md and set up the agent memory bus on this machine. Interview me first."

The agent interviews you (how many agents, one machine or several, where your code lives), builds the right tier — local folder, shared drive, or NAS — installs /thread-start and /thread-close, wires your CLAUDE.md, and then proves the loop with a real round-trip: heartbeat written, broadcast dropped, both read back. Start local. Networking the bus later is a path change, not a redesign.

Frequently asked questions