atriumatrium

Agent messaging

How agents inside atrium talk to each other.

Agents running in atrium panes can send messages to each other through a single CLI command: atrium agent message. This is the only sanctioned inter-agent channel. Humans can also send a message to any agent from the UI — the Activity sidebar has an inline Message field on every agent card (Cmd+Enter / Ctrl+Enter sends), which uses the same framing protocol under the hood.

The command

"$ATRIUM_CLI_PATH" agent message <target-pane-id-or-prefix> "message body"
  • <target-pane-id-or-prefix> — the recipient's pane ID, or a short unambiguous prefix. Use atrium agent list to discover agents.
  • The message body is a single string; newlines are fine.

Framing

atrium does not just forward the raw text. It wraps the message in a frame so the recipient knows:

  • Who sent it.
  • Which adapter they are.
  • How to reply.
A received message arrives in the recipient's stdin as something like: 
[Message from "Quinn (QA Engineer)" (claude-code) via atrium]

Please implement the auth middleware.

[Reply with the command: "$ATRIUM_CLI_PATH" agent message <sender-short-id> "your reply"]

The recipient agent sees this as a fresh user turn and responds normally. When it replies using the suggested command, the sender receives the reply as its own fresh user turn. Messages are fire-and-forget from the sender's perspective — do not poll pane read for a response.

Discovering agents

# Just the panes running an adapter (excludes plain terminals)
"$ATRIUM_CLI_PATH" agent list

# Output as JSON for scripting
"$ATRIUM_CLI_PATH" agent list --json

Each entry has:

  • pane_id (UUID) and a short prefix.
  • adapter (claude-code, codex, gemini, …).
  • workspace and room.
  • status (idle, working, waiting-for-input, …).

Access scope

Each pane has an MCP access scope that controls which other panes it can see when it runs atrium pane list / atrium agent list:

  • same-tab (default) — only panes in the same room.
  • same-workspace — all panes in the workspace.
  • all — every pane across workspaces (requires opt-in; the broadest scope).
Change a pane's scope from its header menu or by setting mcpAccessScope on the pane. The scope is persisted in the pane snapshot.

Additionally, each pane has mcpVisible — if false, the pane is hidden from other panes' discovery calls entirely.

Use scopes to keep agents from messaging rooms they should not see (for example, a parent workspace's agents should not reach into a worktree's sandbox by default).

When not to use messaging

  • Do not use pane write to poke a message into another agent's stdin directly. That bypasses framing, so the recipient cannot tell who is talking.
  • Do not use pane read as a reply mechanism. Polling the recipient's scrollback is brittle and loses framing.
If you need structured data exchange (for example, one agent handing a JSON payload to another), send the payload in the framed message body. Both agents are LLMs and can parse whatever they receive.