I've been building agent-doc [1] to solve exactly this. Each parallel Claude Code session gets its own markdown document as the interface (e.g., tasks/plan.md, tasks/auth.md). The agent reads/writes to the document, and a snapshot-based diff system means each submit only processes what changed — comments are stripped, so you can annotate without triggering responses.
The routing layer uses tmux: `agent-doc claim`, `route`, `focus`, `layout` commands manage which pane owns which document, scoped to tmux windows. A JetBrains plugin lets you submit from the IDE with a hotkey — it finds the right pane and sends the skill command.
For context sync across agents, the key insight was: don't sync. Each agent owns one document with its own conversation history. The orchestration doc (plan.md) references feature docs but doesn't duplicate their content. When an agent finishes a feature, its key decisions get extracted into SPEC.md. The documents ARE the shared context — any agent can read any document.
It's been working well for running 4-6 parallel sessions across corky (email client), agent-doc itself, and a JetBrains plugin — all from one tmux window with window-scoped routing.
The runtime state logging approach makes sense for browser automation — that's a domain where ground truth literally lives outside your repo. We have a similar dynamic with email state in corky (IMAP sync, draft queues). Same pattern: log the external state separately and let the document reference it.
On concurrent editing — it's handled at two levels:
*Ownership:* Each document is claimed by one tmux pane (one agent session). The routing layer prevents two agents from working the same doc simultaneously.
*3-way merge:* If I edit the document while the agent is mid-response, agent-doc detects the change on write-back and runs `git merge-file --diff3` — baseline (pre-commit), agent response, and my concurrent edits all merge. Non-overlapping changes merge cleanly; overlapping changes get conflict markers. Nothing is silently dropped.
The pre-submit git commit is the key — it creates an immutable baseline before the agent touches anything, so there's always a clean reference point for the merge.
The pre-submit commit as an immutable baseline is the key design decision — every agent interaction is an atomic transaction with a known rollback point, exactly right.
On the "event → agent" gap: we've been thinking about this as a layered problem.
The bridge is a file write. agent-doc is user-initiated (edit a doc, hit submit), but the diff pipeline doesn't care who writes the file. A watcher process — or any external system — can write to the file system, and the agent sees the change on next poll.
We already do this in a different layer: corky (https://github.com/btakita/corky), our email tool, runs a watch daemon that polls IMAP for new messages and syncs them to markdown files on disk. External event (email arrives) gets translated into a file-system change, which is the agent's native input format. Same pattern would work for session recovery: monitoring process detects flagged session → writes to a task file → agent picks it up.
Dashboard-as-document is something we're actively planning. The idea: a markdown template where a watcher fills in operational fields — session status, health checks, proxy assignments. When the watcher updates "active" → "flagged", the diff pipeline sees exactly what changed. The template gives structure; the diff gives the trigger.
The snapshot diff already works for this — partial support exists today via agent-doc's routing layer (external scripts can trigger submission when a file changes). What we're building next is auto-submit on file change and sectional write-back so the agent can update specific dashboard fields rather than only appending.
For sub-second latency, a lightweight daemon that receives webhooks and writes to the notification file or directly triggers an agent submit. But for most operational tasks, a polling interval (ours runs every 30 seconds) closes the gap well enough.
The gap you're describing — "thing happened" to "agent knows about it" — is really about who writes the event into the file system. Once it's a file change, the diff pipeline handles the rest.
This maps closely to something we've been exploring in our recent paper. The core issue is that flat context windows don't organize information scalably, so as agents work in parallel they lose track of which version of 'reality' applies to which component. We proposed NERDs (Networked Entity Representation Documents), Wikipedia-style docs that consolidate all info about a code entity (its state, relationships, recent changes) into a single navigable document, corss-linked with other other documents, that any agent can read. The idea is that the shared memory is entity-centered rather than chronological. Might be relevant: https://www.techrxiv.org/users/1021468/articles/1381483-thin...
We talk a little bit about this in the paper, but just a bit. And it is an important question. Real entities change! We’re not just trying to create a representation of now, but a historical record of how we got here. The two ideas we played with that didn’t make it in the paper were
1) explicitly tell the NERD system to keep a timeline for each entity that tracks “core state” changes.
2) Let the NERD-agents also access the full change log of the NERD documents, so that they could see the history of the document. Possibly like a git history. For the paper we left these out because they were both too complicating.
I’ve been using Steve Yegge’s Beads[1] lightweight issue tracker for this type of multi-agent context tracking.
I only run a couple of agents at a time, but with Beads you can create issues, then agents can assign them to themselves, etc. Agents or the human driver can also add context in epics, and I think you can have perpetual issues which contain context too. Or could make them as a type of issue yourself, it’s a very flexible system.
I describe this in the article - I mostly kick off a new agent per spec both for Planners and Workers. I do tend to run /fd-explore before I start work on a given spec to give the agent context of the codebase and recent previous work
