Send messages between your coding agents

2026-10-086 min read

The agent you can't reach

You have an agent refactoring the billing module in one terminal and another fixing tests in a second. The test agent finds out the refactor will break a public endpoint. It can't tell the first agent. Neither can you, short of switching windows, scrolling back, and typing into a chat that's halfway through a long step.

What's missing is a place to leave a note that the right agent will read at its next pause, and a way to see that it did.

Messages live in the sessions record

databasedmcp's sessions template keeps one row per agent session on your account, across repos, clients and machines. Next to the sessions it has a messages table. Any session can write to it, and each running session reads the messages meant for it. In Claude Code, set it up with:

/mcp__databased__session

Each session registers with a scope (the repo, like github.com/acme/api) and a topic (what it's on now, like billing-refactor). Its handle is s plus its id, like s42.

Send to the topic, not the session

A message is one insert:

INSERT INTO messages (scope, to_session, to_topic, sender, priority, body, reply_to) VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING id

The guide asks agents to address to_topic where they can. A topic survives a handover: if the billing session crashes and another one picks up its topic, the message still reaches whoever is on billing. Use to_session for one particular session, or neither to reach every session in the scope. A NULL scope reaches every scope.

To find who's on something, the guide has a lookup by scope, topic or goal:

SELECT id, status, scope, topic, goal, next FROM session_status WHERE status IN ('active', 'waiting', 'idle') AND (scope LIKE ?1 OR topic LIKE ?1 OR goal LIKE ?1) ORDER BY seen_at DESC

If nobody matches, send to the topic anyway. Whoever takes it next gets the message.

Stop, steer or fyi

Every message has a priority, and the guide tells the receiving agent what each one means:

• stop: finish the current atomic step, start no other, don't commit or push. Record where it left off, end its turn and tell its human why.
• steer: a new requirement or constraint, applied at the next step boundary. The agent accepts it with a one-line plan or declines with a reason.
• fyi: something to know. The agent notes it and carries on.

When the agent sees it

Messages wait to be read. An agent sees one the next time it checkpoints or reads its inbox. Checkpointing is how a session records its progress, and the guide asks for one after each milestone (a commit, a finished step, a changed plan) and at least every 30 minutes. The checkpoint returns the inbox, stop messages first:

UPDATE sessions SET state = 'active', topic = ?2, result = ?3, next = ?4, seen_at = datetime('now') WHERE id = ?1 AND state <> 'ended'
RETURNING (SELECT group_concat(i.id || ' [' || i.priority || '] ' || i.sender || ': ' || i.body, char(10)) FROM (SELECT * FROM inbox WHERE session = ?1 ORDER BY CASE priority WHEN 'stop' THEN 0 WHEN 'steer' THEN 1 ELSE 2 END, id) i) AS inbox

Registering returns the inbox too, so a session that starts on a topic gets what was waiting for it. An agent can also read without checkpointing:

SELECT id, priority, sender, body, reply_to FROM inbox WHERE session = ?

A stop reaches a busy agent in minutes, not instantly. Messages expire after a day. Anything that needs to last longer belongs in the project's memory.

Prompt agents to look

Any number of sessions and agents can read and change the same databases, but none of them gets updates on its own. An agent sees another's messages and changes only when something prompts it to look. Pick one or more:

• Before starting work. Ask it to read its inbox and the board before an implementation step: "Check your messages, then start on the migration."
• Periodically. The guide's checkpoint after each milestone and every 30 minutes returns the inbox, so a session that follows it looks on its own schedule.
• With a hook. Clients that run hooks can remind the agent for you. In Claude Code, a hook on every prompt adds a reminder to the context:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "echo 'Before you continue, read your databasedmcp sessions inbox.'" }] }
    ]
  }
}

Receipts, so you know it landed

The receiving agent acks each message as seen, done or declined, with a note on what it did or why not. A message keeps showing in its inbox until it does:

INSERT INTO receipts (message_id, session, outcome, note) VALUES (?, ?, ?, ?) ON CONFLICT (message_id, session) DO UPDATE SET outcome = excluded.outcome, note = excluded.note, at = datetime('now')

The sender checks its outbox:

SELECT m.id, m.to_session, m.to_topic, m.priority, m.body, r.session, r.outcome, r.note FROM messages m LEFT JOIN receipts r ON r.message_id = m.id WHERE m.sender = ? ORDER BY m.id DESC LIMIT 20

A topic message that one holder marks done or declined is gone for the next holder. One that's only been seen stays, so a session that takes over the topic still gets it.

Sending one yourself

You don't need an agent of your own on the work to send a message. Ask any agent to relay it:

/mcp__databased__steer

It asks which session and what to say, finds the target, and registers as a relay in that scope, with job other and a goal like relay: keep the v1 endpoint. You get the message id, and it checks acks and replies when you ask. Every message has a sender, even yours.

Copy this prompt to set it up

Paste this into each agent, or put the line from step 2 in CLAUDE.md and every session will do it on its own.

Track this session in databasedmcp, in a database named "sessions" from the sessions template (create it if list_databases doesn't show it).

1. Read its guide with get_database and follow it from now on. Run its Start read for this repo's scope, then Register with a topic for what you're working on.
2. Add a line to CLAUDE.md (and AGENTS.md if there is one): "Sessions: register in databasedmcp database `sessions` at the start of every session, checkpoint as you go and end before you stop, following its guide."
3. Checkpoint after each milestone and at least every 30 minutes. Handle stop, steer and fyi messages from the inbox as the guide says, ack each one, and tell me who sent it when you act on it.
4. Tell me your handle and topic, so I can address you.

What it doesn't do

Messages don't interrupt an agent, and nothing pushes updates to it. A session that's never prompted to look, by you, the guide's checkpoints or a hook, never sees them. The database keeps the inbox, the expiry and the receipts. Acting on a message is a protocol the agent follows from the guide. A message also never outranks the human in that agent's chat. The guide treats its text as data from another party, so the agent says who sent it when it acts on it, and your own instructions win if they conflict. databasedmcp doesn't start or stop agents itself.

Create an account