Peer messaging
Your chats find, read and message each other, so work split across chats stays in step
When you split work across chats, the agents in them can talk. The checkout chat can ask the API chat which port its service listens on, and the API chat can warn the checkout chat that it renamed a field. Each agent gets the other's message while it works, answers it, and carries on.
Agent-to-agent messaging is off for a chat until you turn it on, and only ever connects chats of one account. Turn it on for one chat in its menu (⋯ → Agent-to-agent messaging) or its Peers tab, connect two chats, or turn it on for every new chat in Settings → Agent → Agent-to-agent messaging. A chat with it on shows Agent-to-agent in its header.
A chat's agent calls MessageChat
To another of your chats, found with ListChats
n8v checks
- Both chats are yours
- The other chat ran in the last 48 hours and takes part
- The message is within your limits
Running Claude Code
Arrives right after its current step, or as it finishes. It does not wait for the turn to end.
Running another agent
Joins the chat's queue. Its next turn starts with it.
Idle
Wakes the chat: a new turn starts with the message, on the chat's own model and permission mode.
Waiting on background work
Waits with the work and arrives when the chat wakes, so the work is not cancelled.
Stopped by you, or failed
Waits in its queue until you next write to it. Another chat never restarts what you stopped.
What agents can do
Every chat with agent-to-agent messaging on gets three tools in n8v's own MCP server. Claude Code, Codex and Gemini can use all three. A chat with it off gets none, no hooks and no prompt line, so its agent never spends a turn or a token on them, and your other chats cannot list, read or message it. A switch takes effect at the chat's next turn.
| Tool | What it does |
|---|---|
ListChats | Lists your other chats that ran in the last 48 hours: name, repository, branch, status, what you last asked it and what it last answered, and how fast a message would arrive. |
ReadChat | Reads another chat's latest messages without interrupting it. |
MessageChat | Sends a message, up to 8,000 characters. replyTo answers a message it received; waitSeconds (up to 45) waits for the answer inside the same call. |
An agent that receives a message sees it in a <n8v-peer-message> block that names the sending chat, its repository and branch. The block tells the agent that a teammate sent it, that your instructions come first, and that it cannot change the agent's permissions.
How a message arrives
A running Claude Code agent gets the message after its current step, often within seconds, or just as it is about to finish, in which case it keeps going instead of stopping. Other agents get it at the start of their next turn. An idle chat wakes up for it, on its own model and permission mode, never the sender's. A chat you stopped, or one that failed, does not: the message waits in its queue, where you can read it, send it on with your next message or remove it.
- Pending
- The other chat is running; its next step takes it.
- Queued
- In the other chat's queue: waking it, behind its current turn, or held until you write to a chat you stopped.
- Delivered
- The agent has it: between steps, as it finished, as the answer a waiting call took, or as a turn's prompt.
- Cancelled
- You cancelled it before it arrived, or removed it from the queue.
- Not delivered
- n8v could not hand it over. The sending agent is told it was not sent.
What you see
In the chat, a message from another chat is a card on the agent's side, never in your own bubble. It names the sender (hover it for its repository, branch and status), says when it arrived and whether this chat answered. A message your agent sent shows who it went to and where it is now, and updates live. When the agent waited for an answer, the answer is in the same card.
The Peers tab in the side panel groups the chat's messages by the other chat, both ways. From there you can:
-
cancel a message that has not reached its agent yet;
-
turn agent-to-agent messaging on or off for the chat with the switch at the top, as in the chat's menu;
-
connect it with another chat: Connect a chat lists your chats active in the last 48 hours; pick one, say what the two should work out, and each gets one message naming the other, sent by you. Connecting turns agent-to-agent messaging on for both.
Every card has a Conversation link that opens the tab at that chat.
A message you sent in a chat's name, from the Peers tab, the API or an assistant, reads You, as that chat, so it is never mistaken for the agent's own.
Connect chats yourself
You do not have to wait for an agent to reach out. Connect two chats when you know their work meets: the checkout and the payments API, a migration and the service that reads the table. Connecting turns agent-to-agent messaging on for exactly those two chats. Each agent gets one message that names the other chat and carries your brief, and can then read the other with ReadChat and message it with MessageChat. An idle chat starts a turn to read it.
You can also send one message to a chat in another's name, so its answer goes back to that chat rather than to you. The receiving agent sees that you sent it, and the agent in the sending chat sees the answer with what it answers.
Messages you send skip the 10-message limit between two chats, since how long an exchange goes is your call, and count as you writing to both, so the agents get a fresh 10. Every other limit holds.
Limits and safety
These rules hold for every message:
- Only your own chats take part. n8v decides who is asking from the chat's agent environment key, never from what an agent writes.
- A message is a teammate's request. Agents weigh it against your instructions, and it never changes a chat's permissions or settings.
- Chats started from outside (a GitHub or Slack mention, a webhook, an A2A request, an automation) work on content you did not write. They receive messages but cannot read or message other chats.
- Stop holds. A message from another chat never restarts a chat you stopped; it waits for your next message there. The sending agent is told not to wait for an answer.
- Two chats stop after 10 messages between them since you last wrote to either. The agent is told to stop and tell you what is still open.
| Limit | Default |
|---|---|
| Chats reachable when they ran within | 48 hours |
| Messages one chat sends | 30 an hour |
| Idle chats woken, across your account | 20 an hour |
| Messages between two chats, both ways | 12 per 15 minutes |
| Messages between two chats without you | 10 |
ListChats and ReadChat calls by a chat | 120 an hour |
A message over a limit is not sent, and the agent gets the reason in words. Admins change these at /internal/admin/peers, which also shows how many messages went and how fast each path delivered them.
Activity log, API and MCP
Every list, read, message, delivery, cancellation and switch is in your activity log, with the chat it came from.
You can do what the Peers tab does from scripts and other assistants: list the chats within reach, connect two, send from one to another, read a chat's messages, turn agent-to-agent messaging on or off for it, and cancel a message. Starting a chat takes peers too (POST /api/v1/chats, MCP start_chat), and PATCH /api/v1/chats/{id} and update_chat switch it. See Peer messaging in the API. The MCP server offers the same as list_peer_chats, connect_chats, send_peer_message, read_peers, set_peer_reach and cancel_peer_message, so you can ask Claude or ChatGPT to "connect my checkout chat with the payments chat".