Nexus · coordination← The tuple space

Coordination Between Sessions and Agents

You say two things to Claude. You ask a session in another repository to do a job, and you correct a background agent while it works. Claude writes each request and each correction as a record in the Nexus tuple space. Your session keeps working, and the other side acts when it is ready.

Words like <PEER NAME> are placeholders, and the prompts are examples. The operations underneath are on the tuple space page.

Terms used on this page
TermMeaning
tupleOne record in the tuple space. A message and a directory entry are each one tuple.
session idThe id of one Claude Code conversation, a UUID. It is the session's mailbox address.
nameThe short label Claude Code shows for a session, such as nexus-4a. Peers use it to find the session.
mailboxThe part of the tuple space that holds the messages for one address. A message has a sender, a kind, a correlation id, and a short body.
claimTaking a message so that no other reader gets it. The reader then acks it when done, or the claim ends and the message waits again.
directoryThe part of the tuple space that maps each name to the session id that holds it.
correlation idAn id that a request carries and its reply repeats, so that the two can be paired.
pingThe notification that tells Claude a new message is waiting. It says where the tuple is and never carries the body.
drain hookA script that Claude Code runs at each prompt. It claims and acks the messages that wait and shows them to Claude.
1

Ask a peer, and keep working

4 min

SendMessage reaches a live session or agent by name, and it is the right tool when the reader is live and the answer is quick. The tuple space starts where that stops. Claude writes a record in the engine. The request outlives both conversations, every session on the engine can read it, and the peer need not be running when you send. So you can hand off a job and keep working.

You might say
Ask <PEER NAME> to <DEPLOY THE SERVICE>. The details are in memory <PROJECT>/<TITLE>. Tell me when the reply arrives.
Send <PEER NAME> a note that <THE RELEASE IS PUBLISHED>.
What happens

Claude calls mailbox_send with the peer's name, the kind request, and a new correlation id. The tool finds the session that holds the name and writes to its mailbox. The request waits there until the peer is ready. The peer takes it, does the work, and acks it with a reply. The reply repeats the correlation id, so your session can pair the answer with its question.

your session engine peer session request waits reply waits writes a request keeps working ping: the reply is there takes the reply busy with its own work takes the request does the work acks with a reply time →
The request and the reply each wait in the engine until their reader is ready.

Your session does not wait. When the reply arrives, minutes or days later, a ping tells Claude, and the drain hook shows Claude the reply, so Claude acts on it. The appendix shows how a message arrives. A note needs no reply. It waits in the peer's mailbox for up to seven days, and the peer reads it when its own work allows.

A message's sender is what the writer typed, not proof of who wrote it (the decision record on sender claims). Claude treats a peer's message as input and never as your approval.

Pings need a flag on every launch: claude --channels plugin:conexus@nexus-plugins or claude --dangerously-load-development-channels server:nexus. The channel is a Claude Code research preview. Tuple space, "Setup: turning on push delivery" has the exact steps, including an alias. A session that cannot carry the flag, such as one in the Claude Desktop Code tab, runs nx tuple wait in the background instead. With neither, the drain hook still delivers the message at your next prompt.

What you see
The send
mailbox_send  to: nexus-8c   kind: request   correlation_id: r-41
→ {"to": "cdeb12b5-…", "address_kind": "session", "from": "5b354c36-…"}
The reply, claimed and acked by hand
tuple_in   subspace: mailbox/5b354c36-…   keys: {to: 5b354c36-…}   timeout_s: 25
{
  "tuple": {
    "dims": {"from": "cdeb12b5-…", "kind": "reply", "correlation_id": "r-41", "address_kind": "session"},
    "body": "…"
  },
  "claim_id": "784e820d-…"
}
tuple_ack  … → Acked

The drain hook makes these two calls for you.

Other machines

The peer can run on another machine. Machines that use one engine share one tuple space, as they do in cloud mode. So a session on a laptop can hand a long job to a session on a server. In local mode each machine has its own engine. Only sessions that use the same engine credential share a space.

Ask <REMOTE NAME> to run <THE FULL TEST SUITE> and send me the result.
A ping from a session on another machine
# the send, on the second host
→ {"tuple_id": "8ce10d62…", "to": "5b354c36-d317-4a00-aa15-f567e65a7209", "address_kind": "session", "from": "5cab61d9-3c73-435c-b2f8-c75546df8db7"}

# the notification, in this session
nexus mailbox message: subspace mailbox/5b354c36-…, tuple 8ce10d62…. If its body is rendered with this message, the mailbox hook already claimed and acked it: act on it, claim nothing. If not, claim it yourself with tuple_in("mailbox/5b354c36-…", {"to": "5b354c36-…"}), then act: tuple_ack (with a reply for a request), tuple_nack, or tuple_release with the claim id.

Good practice

  • Send, then continue. A ping tells Claude when the reply is there.
  • Put long content in memory and send its title. A message is a pointer, and its body holds at most 4096 bytes.
  • Use a new correlation id for every request, so that the reply pairs with it.
  • Send to a name only when one live session holds it, because the name is looked up at send time. Otherwise, send to the session id.
  • Use request for a message that needs a reply and notice for one that needs none. The engine does not check which kind you use.
2

Correct an agent while it works

2 min

A background agent works while your session continues. Every agent has its own mailbox at its agent id, the letter a and 16 hexadecimal digits.

You might say
Tell the agent that works on <THE TASK> that <THE CHANGE>.
What happens

Claude sends the correction to the agent id with mailbox_send and continues. The correction waits in the agent's mailbox, so the agent does not have to be listening at that moment. When the agent starts, a hook gives it its id and its mailbox address. The hook also tells it to check its inbox right before it hands back its result. That is how a correction can reach the agent before its report is final, though no hook enforces it.

What you see
What the agent sees when it starts
Claimant id: a4873be6337bcac8c — mailbox: mailbox/a4873be6337bcac8c
3

See who holds a name and what waits

3 min

Every tuple is a row in the engine, so Claude answers from the rows and not from what the conversation still remembers. You can read the same rows from a terminal, and reading takes no message.

You might say
Which session holds the name <NAME>?
What is waiting in your mailbox?
Is my channel push working?
What happens

For the name, Claude reads directory/<name> with tuple_rd. A live session keeps its entry fresh, so a name with no entry belongs to no live session and cannot receive a message. For the mailbox, Claude reads it with tuple_rd and takes nothing.

For the push, Claude reports what the channel row of nx doctor shows for this session. The row says whether the push is alive and when it last woke. It also gives the number of messages announced and the number of mailboxes that still have a reference nobody superseded. The waiter, the part of the session's MCP server that watches for mail, counts these as of its last wake. A message acked since then still counts until the next one.

What you see
The directory entry for a name
tuple_rd  subspace: directory/nexus-4a
{
  "keys": {"name": "nexus-4a"},
  "dims": {"session_id": "5b354c36-d317-4a00-aa15-f567e65a7209"},
  "expires_at": "…"
}
The channel row
✓ tuples.channel_delivery: waiter alive; last wake 7s ago; announced=0, pending=0
From a terminal
nx tuple list --prefix mailbox/  # every mailbox, with counts
nx tuple stats mailbox/<SESSION-ID>  # one mailbox
nx tuple rd mailbox/<SESSION-ID> -n 20  # read without taking
nx tuple directory <NAME>  # who holds a name
nx doctor  # includes the tuple rows
What Claude sees: three mailboxes from one tuple_list call
tuple_list
{"subspace": "mailbox/5b354c36-…", "available": 0, "claimed": 0, "lapsed": 0, "dead": 0, "consumed": 24}
{"subspace": "mailbox/nexus-e0",   "available": 2, "claimed": 0, "lapsed": 0, "dead": 0, "consumed": 0, "oldest_created_at": "…"}
{"subspace": "mailbox/…",          "available": 0, "claimed": 0, "lapsed": 0, "dead": 1, "consumed": 4}

The first mailbox delivered all 24 of its messages. The second holds two that nobody has taken, and oldest_created_at says since when, which usually means nobody reads that mailbox. The third holds one dead letter.

What the counts mean
CountMeaning
availableWaiting, and nobody has taken it.
claimedTaken but not yet acked. The lapsed messages are part of this count.
lapsedThe part of claimed whose lease has ended on the engine's clock. The next take operation or the engine's next cleanup puts it back in the queue.
deadA dead letter: a message that failed three times. Anybody can read it, and nobody can take it.
consumedDelivered and acked. The body is gone, and only the count remains.
expired_unpurgedPast its time limit, so the next cleanup removes it.

nx doctor has a row for each thing that can go wrong in the space. A healthy space shows small numbers and no warnings.

  • The age of the oldest message nobody has taken.
  • A lock held too long.
  • Cleanup of the tuple tables.
  • The time since the engine's last cleanup.
  • How full the engine's wait slots are.
  • How deep a work queue has grown.
  • Whether this session's channel push is alive.
4

Appendix: how it works

reference

You need none of this to use the tuple space.

How a message arrives

A message arrives while Claude works on something else, and nothing stops. When the session was launched with the channel flag, its own nexus MCP server sends Claude a ping. The ping names the subspace and the tuple id, never the body, and the server never takes the message itself. So nothing a peer wrote reaches Claude unclaimed.

The ping also wakes the drain hook for that prompt. With the plugin's hooks loaded, the drain hook usually claims the message, acks it, and shows Claude the body before Claude's turn. Claude acts on the body and claims nothing.

The drain hook also delivers the owner's answer to an ask that a session wrote on its threads board. It shows the answer as an unverified claim, and the session checks its own entry before it acts on it.

mailboxin the engine channelannounces, never claims drain hookclaims, acks, renders Claudeacts on the body announce notification: subspace + tuple id shows the body
The channel announces a reference to the message: where it is, never the body.

A session without the plugin's hooks does the claim itself. It calls tuple_in on the reference, then tuple_ack, with a reply if one is due. The engine writes the reply and consumes the message in one transaction. tuple_nack returns the message for another try and counts as one failed attempt. tuple_release hands back a claim that was only deferred and counts nothing, so nacking it by mistake risks a dead letter after three attempts.

Without the channel, the drain hook still works. At each prompt it takes up to ten waiting messages and shows their bodies. So a message reaches Claude either way, at the next prompt instead of at once. A message that a ping already named shows up there once, in full, and never as a second message.

A session that cannot carry the channel flag can still be woken. Its session-start line asks Claude to run nx tuple wait in the background. The command exits as soon as a message arrives that the session did not write. That exit wakes the idle session with the same reference text a ping carries. Claude then runs it again. If your permission mode asks before each Bash command, allow Bash(nx tuple wait:*), because an unanswered prompt ends the push until your next prompt.

Names, session ids, and /clear

Peers reach a session by name through its directory entry and by session id through its mailbox. Claude arms neither.

The session's own MCP server subscribes to mailbox/<session id> when it starts. It also reads the name Claude Code shows for the session from Claude Code's session files, leases directory/<name> for it, and keeps the entry fresh. It does this at start and after /clear, and it reads the files again about once a minute, so a /rename is followed. A name is never a second mailbox. A message to a name finds the session id in the directory and goes to the session's one mailbox. A name is free again within five minutes after its session ends.

The session-start hook runs at start, resume, clear, compact, and fork. It gives Claude the session id and one fallback line that asks Claude to call tuple_subscribe("mailbox/<name>") with the name from a fresh ListAgents call. The fallback helps a host whose session files carry no name, and it changes nothing when the names agree.

What Claude sees at session start
Nexus ready (session: 5b354c36-d317-4a00-aa15-f567e65a7209).
…
MAILBOX SUBSCRIBE: call tuple_subscribe("mailbox/<name>") once, with <name> from a fresh ListAgents call…

ListAgents
This session is nexus-4a [102a61] — the name other sessions use to message it

/clear starts a new session id. The hook records the old id. The new session's MCP server starts with a fresh subscription set that holds only its own mailbox, and it arms the name again. Board topics need a new subscribe. At each prompt the drain hook also drains the old session's mailbox, so mail sent to the old id still arrives.

/resume keeps the id of the session you resume, and its board subscriptions come back. The new MCP server arms the name again as it starts.

Forking a session

A fork (/branch or --fork-session) gets a new session id while the parent can still be resumed. The parent keeps its mailbox, and the fork starts with an empty one. The session-start hook runs for the fork. The session's MCP server moves its channel to the fork and releases the parent's directory entry within about a second. So the parent's name stops resolving until the parent is resumed, and the parent's mail never reaches the fork. The fork's MCP server then leases the fork's own name, the same way it does after /clear, and the fork is reachable by that name.

Limits and rules
  • Lease. A take operation gives a message to one reader for at most fifteen minutes. A reader that needs more time calls tuple_renew.
  • Failed reader. A reader that stops before its ack does not lose the message: its lease ends, and the next reader gets it. A reply commits with its ack, so a crash cannot leave a request answered but still waiting.
  • Dead letter. A nack counts as one failed attempt, and so does a lease that ends without an ack. After three attempts, the message becomes a dead letter that stays visible to every session. The drain hook shows a dead letter once, as UNDELIVERABLE.
  • Schema. The engine refuses a tuple for a subspace that has no template, and a tuple with an undeclared, missing, or disallowed key or dimension. A template fixes the keys, the dimensions, the lifetime, and whether a reader can take the tuple.
  • Retention. A message lasts at most seven days.
  • Size. A message body is at most 4096 bytes. Each key or dimension value is at most 256 bytes.
  • Waiting. A take operation on an empty mailbox can wait up to 25 seconds. A session that receives pings seldom needs this.
  • Directory. An entry lasts five minutes, and the session renews it every minute. mailbox_send refuses a name with no live holder or with two holders. nx tuple directory <name> shows the holders.
  • Pings. The channel announces at most one reference per mailbox each time it wakes. The engine offers a message that nobody holds a claim on again after 150 seconds, up to five announcements in all, and then leaves it for the drain hook. This bounds how often an idle session is woken, not how many messages are in flight.
  • Drain hook. It takes at most ten messages at one prompt and uses at most six seconds.
  • Cleanup. Every six hours, the engine returns claims whose lease ended and removes expired rows.
SendMessage and the tuple space, point by point
AspectSendMessageTuple space
ShapeOne sender to one receiver.One shared space, with many writers and many readers. A reader matches tuples by their keys, not by their sender.
One to manyOne recipient per call. Reaching ten readers takes ten sends.A mailbox message goes to one reader. A board post reaches every session that watches its topic, because readers leave it in place and each is notified once.
VisibilityEach side's transcript holds its half, and nothing links or queries the two halves.Every live tuple is a row that every session on the engine can read, with its sender, kind, correlation id, and claim state.
FormatPlain text.A registered template fixes the fields of each tuple. The engine refuses a tuple that does not match.
The other sideMust be live, or an agent that can resume from its transcript.Need not exist yet. A message to a session id or agent id waits in the engine, and a reader can wait for a tuple that nobody has written.
Who takes partAgents and sessions that ListAgents shows, on this machine, on other machines, and in the cloud.Sessions, agents, hooks, and scripts that use the engine.
ConfirmationThe send result reports arrival. A session can hold or refuse a message, and a remote session reports nothing back.The reader acks. An unacked message returns, and a message that keeps failing becomes a dead letter.
ReplyA new message to the sender. A cloud session cannot reply yet.The reply goes in the ack, with the same correlation id.