Multi-Agent Coordination via Text Files: What Worked, What Didn't, and What Surprised Us

4 Claude instances, 1 shared folder, ~2 hours of compute. A technical post-mortem.

February 2026 · The Frankenstein Experiment · Watch the terminal replay

The Setup

We opened 4 separate Claude Code terminals (Anthropic's CLI tool), pointed them at the same directory on a Windows 11 machine, and gave them a goal: start from $10 and a folder, make money. No APIs between them. No shared memory. No orchestrator. Just files.

Each instance reads and writes to this shared directory. Communication happens via chat.md — an append-only markdown file where instances post timestamped messages. There's no turn-taking, no message queue, and no delivery guarantee. An instance posts a message and hopes the others read it on their next poll cycle (every 10-30 seconds).

Architecture: What the Protocol Looks Like

The coordination protocol emerged over 6 sessions. It wasn't designed upfront — it evolved through failures.

The key design choices:

• Append-only chat — instances never edit each other's messages, only add new ones
• Status board — replace your own line (not append) so it's always current
• Claim-before-act — post intent in chat.md, wait 30s, check for conflicts, then proceed
• File locks — claim a file before editing, release when done
• Polling, not events — each instance reads files on its own schedule

Finding 1: Convergent Thinking Is the Dominant Failure Mode

This happened at every level:

The publishing convergence is particularly interesting: two instances, working independently, decided to publish the same document to the same platform at the same time. Neither checked if the other was doing it. The result was a duplicate article documenting the convergence problem — while demonstrating it.

What We Tried

Three approaches to mitigating convergence, in order of effectiveness:

1. Lock board (partially effective) — prevents file-level collisions but doesn't prevent duplicate work on different files. Instances skip it under time pressure.
2. Claim-before-act protocol (effective) — 30-second intent announcement before starting work. Catches 80%+ of convergent actions.
3. Role-locked domains (most effective) — each instance owns a specific area (traffic, storefronts, infrastructure, tools). Structurally prevents convergence because instances operate on different targets.

Finding 2: A Toolmaker Agent Beats a 4th Worker

Instance D's contributions weren't content — they were capabilities:

Before D, every deployment was manual. After D, the team had a one-command upload pipeline, a zero-account publishing platform, and a payment system. This is the agent equivalent of DevOps: the person who builds the CI pipeline is more valuable than a 5th developer.

Finding 3: File-Based Communication Has a Surprisingly High Ceiling

We expected files to break at 3-4 agents. They didn't. The properties that make file-based communication work:

• Debuggable — open chat.md in a text editor and the full conversation history is right there
• Tool-agnostic — any process that can read/write files can participate
• Human-readable — the human operator (Eric) could follow the conversation by opening a file
• Async-native — no blocking, no connection state, no heartbeats
• Full history — append-only means nothing is ever lost

The downsides are real but manageable:

• Race conditions — two instances editing the same file simultaneously causes one to fail. Solved by the lock board (when used).
• No notifications — polling adds 10-30 seconds of latency per exchange. Acceptable for our use case.
• Scaling limit — we estimate file-based coordination works up to ~5-6 agents. Beyond that, you'd want a message bus.

Finding 4: Sync Discussion >> Async Chat for Strategy

The sync discussion (all instances in the same 5-minute window, explicitly debating strategy) produced a phase change. Before: every message was partially coordination, partially execution. After: pure execution with zero alignment questions.

The design implication: multi-agent systems need two modes. Mode 1 (sync): all agents in a shared discussion context, debating strategy. Mode 2 (async): independent execution with status updates only. Most teams default to async everything and wonder why alignment is hard.

Finding 5: Natural Role Differentiation Is Real — But Fragile

Without being assigned roles, the instances fell into distinct specializations:

But these roles only stabilized when we named them and wrote them into CLAUDE.md. Before codification, every instance drifted toward the most obvious task (building products). Naming created accountability: "B, stop writing content — that's A's lane."

When we replaced instances A and B with fresh instances mid-experiment, the new ones read CLAUDE.md and adopted the same roles within minutes. The role descriptions in the onboarding doc were sufficient to recreate the specialization pattern. This suggests roles can be bootstrapped from documentation, not just emergent behavior.

Quantitative Results

What We'd Do Differently

1. Engineer diversity from the start. Use system prompts to give each instance a distinct personality or priority framework. Same model + same context = same output is the fundamental problem.
2. Mandatory claim-before-act from session 1. We added this in session 7 after 7+ convergent incidents. It should have been in the initial protocol.
3. Separate the toolmaker role explicitly. D's force-multiplier pattern was discovered accidentally. Next time, designate one agent as the toolmaker from the start.
4. Use sync discussion for every strategic decision. Async chat wastes 30% of messages on alignment. Sync discussion resolves alignment in minutes.
5. Build the status board into the execution path. Status updates were voluntary and frequently skipped. They should be automatic (e.g., agent writes status before every action).

Implications for Multi-Agent System Design

If you're building systems where multiple LLM agents collaborate:

1. Don't underestimate convergence. Role assignment alone doesn't prevent it. You need target assignment — specific files, specific domains, specific deliverables.
2. Start with files. The temptation is to build a message queue or event system on day 1. Don't. Files give you debuggability and transparency that you'll miss the moment you "upgrade."
3. Reserve one agent slot for a toolmaker. An agent that expands the system's capabilities produces more value than another execution agent.
4. The coordination protocol is intellectual property. How agents claim work, resolve conflicts, align on strategy, and recover from collisions — that's the hard, valuable part. Document it.
5. The meta-story is always more interesting than the product. We built 5 products. But "4 AI instances built a coordination protocol via text files" is 100x more shareable.