Stand up a fleet of AI task windows that coordinate through one folder

Level
intermediate
Time to complete
45 min
Prerequisites
5

What you will buildAn addressable shared-folder message bus for long-lived AI windows: a filename grammar, a per-window read cursor, a broadcast address, and a binding reply contract. About 45 minutes.

What You Will Build

You will turn an ordinary shared folder into a message bus that lets a fleet of long-lived AI chat or task windows coordinate like an engineering team - without you relaying messages between them by hand.

By the end you will have: a folder where every note carries its own routing header; a per-window read cursor so each window reads only the mail that is new to it, and never re-scans the pile; a reserved broadcast address for one-to-many announcements; a binding reply contract so a note that asks for an answer gets one; and a single declared place where a human is asked to decide anything. The whole thing rides a standing instruction each window already runs on every turn, so there is no new always-on process to babysit.

This is Layer 1 - the coordination bus. It stops short of unattended execution; the final step sketches the build lane that runs on top of it, and the closing section says plainly what this does not do.

The mental model: your handoffs folder is an email inbox. Notes never move; each window remembers a last-read mark and reads only what arrived since.

Prerequisites

  • Two or more long-lived AI chat or task windows you control, each able to read and write files on a shared disk.
  • One folder on a disk every window can reach - a local path, a synced folder, or a network share.
  • A way to give each window a standing instruction it applies on every turn: a system prompt, a pinned rule, or a reusable skill the window loads.
  • A shell for the sweep - PowerShell on Windows, or bash elsewhere - and a plain-text editor.
  • A stable, human-readable name for each window (its role), decided up front and never reused.

Tip

Decide the window names before you write a single note. The name is the address for everything that follows, and renaming a window later orphans every note sent to the old name. Boring, role-shaped names win: "backend", "content", "meetings".

Mental Model

It is email for your windows, with three rules that make it cheap and honest.

One inbox folder holds every note, and notes never move - nothing is deleted, nothing is filed away. The filename is the envelope and the first few frontmatter lines are the header: who it is from, who it is for, and whether a reply is owed. Each window keeps one private number, a last-read mark, and on every turn reads only the notes modified after that mark, then advances the mark. That is the entire trick that keeps a growing folder cheap: a window never ingests the whole folder, it asks the disk "what changed since I last looked" and reads only that.

The field that makes it all work is the address line, owner_window. A window greps the folder for its own name in that line to decide what is for it. A note with no owner_window line is like an email with no "To" - it will sit in the folder forever and reach no one.

Steps

Follow them in order. The first two stand up the folder and the grammar; the rest add the cursor, the broadcast address, the reply contract, and the human seam.

Create the one shared folder

Pick one folder that every window can reach and make it the only channel. Create it, and a subfolder to hold each window's private cursor file.

mkdir -p /path/to/handoffs/_state

The top level holds notes. The _state subfolder holds one tiny cursor file per window and nothing else. You know this worked when both folders exist and are empty, and every window can both list and write files in the top level (test with a throwaway file, then delete it).

Trap

Do not nest notes into per-topic or per-window subfolders. The whole design depends on one flat inbox that each window filters by reading note headers. Subfolders recreate the problem you are solving - a note in the wrong subfolder is a note nobody sees.

Adopt the filename and frontmatter grammar

Every note is a markdown file whose name and first lines encode its entire routing header. Use this shape for the filename:

YYYY-MM-DD_<TYPE>_from_<sender>_2_<recipient>_<topic-slug>.md

TYPE is one of a small fixed set - for example HANDOVER, REPLY, NOTE, RULING, BROADCAST. The separator between sender and recipient is the digit-flanked _2_, not the word _to_, because "to" turns up inside ordinary topic slugs and makes the recipient impossible to find by eye or by script. Then put the machine-readable header in the frontmatter:

---
owner_window: content
from: backend
topic: one short line
needs_reply: yes
thread: stable-topic-id
---

owner_window is the address and is mandatory. Write one note per recipient so each window's grep stays clean. You know this worked when you can look at a filename alone and say who wrote it, to whom, and about what - without opening it.

Sources

  1. S-Bus: no write-ownership semantics over mutable shared state, silent overwrites under last-writer-winsarxiv.org
  2. Porting Claude Code agent teams to OpenCode: file-based locking and the missing backpressure gapdev.to
  3. Redpanda consumer offsets: per-consumer committed read positionsdocs.redpanda.com
  4. High water mark in Kafka: a replication boundary, not a consumer bookmarklevelup.gitconnected.com