Workstate Docs

Pattern: multi-agent coordination ​

Several agents working on the same system without redoing or undoing each other's work.

Who it's for ​

Teams where several agents touch the same system. They might be each developer's coding agent, parallel agents run by one person, or automated agents your team built.

How agents stay out of each other's way today ​

Workstate doesn't run or schedule agents. It gives them one shared record and three habits:

  1. Search before acting. At the start of a task, the agent calls ledger_search for the component it's about to change. It filters by project and, where useful, by type or status. It reads anything relevant in full with ledger_get.
  2. Record after. When it finishes, it records each decision or finding as its own topic with ledger_create.
  3. Supersede, don't overwrite. If its decision replaces an earlier one, it creates a new topic. Then it calls ledger_append on the new topic with supersedes set to the old id. Workstate links the two both ways and marks the old topic superseded.

Every record carries the person whose API key wrote it, and an agent label. The label comes from the tool's agent argument or the X-RAG-Agent header, so give each agent a label that tells it apart.

An illustrative sequence ​

Illustrative

Monday. Agent A, one developer's Claude Code, compares retry strategies for the notification service. It records notify-0008, a decision: exponential backoff with jitter, at most five attempts. It notes that a circuit breaker was rejected for now.

Wednesday. Agent B, another developer's Cursor, is asked to make notifications more reliable. Before writing code, it searches the ledger:

json
{ "query": "retry policy for sending notifications", "repo": "notify", "type": "decision" }

It finds notify-0008, reads it with ledger_get and follows it. It doesn't repeat the comparison, and it cites notify-0008 in its pull request.

Friday. Agent C learns that the email provider rate-limits retries, so five attempts make things worse. It records notify-0011 with the new policy, then supersedes the old decision:

json
{ "topic_id": "notify-0011", "body": "Replaces notify-0008: the provider rate-limits retries.", "supersedes": "notify-0008" }

A search now finds both topics. notify-0008 shows as superseded and links to notify-0011, and the reason for the change is on record.

How to split namespaces and projects ​

  • Agents that must coordinate share a namespace. A namespace can't see another namespace's sources or ledger.
  • Split namespaces by who may see the content, not by agent or by team size. See Namespaces.
  • Within a namespace, use projects. Every topic belongs to a project, and agents filter on it. For code, name the project after the repository. Topic ids then read like notify-0008, and one filter narrows both code and ledger searches.
  • Give each machine or agent its own key. All of a person's keys attribute to that person, but you can revoke one without stopping the others.

Instructions to give your agents ​

Add these rules to the shared agent instructions:

md
- Before you start, call ledger_search for the component you will change, with the repo filter. Read relevant topics with ledger_get. Follow accepted decisions; if you disagree, say so and ask before changing course.
- When you finish, record each decision, root cause or dead end as its own topic with ledger_create. Set agent to your name.
- If your decision replaces an earlier one, create the new topic, then call ledger_append on it with supersedes set to the old topic id.
- For long work that others might also pick up, open an investigation topic when you start, with the current state "in progress", and update it when you stop.

Limits to know ​

  • There's no lock. Two agents that start the same work at the same moment won't see each other. A new topic becomes searchable within about 5 seconds, and ledger_get finds it straight away.
  • Claims on work Coming soon, addressed questions Coming soon and briefings when a session starts Coming soon aren't available yet.
  • The person behind a record is authenticated by their key. The agent label is whatever the client sends.
  • The habits work only if every agent follows them, so put them in every agent's instructions.

Next steps ​

Workstate is built by Nerdstorm Pty Ltd, Sydney.