| name | msg |
| description | Read or write the cross-session mailbox by @id. Send a message to another Claude Code session (`/msg @name text`), read your own inbox (`/msg` with no args), broadcast to everyone (`/msg all text`), list the whole bus, or discover who is reachable. Thin wrapper over the `kei message` jsonl mailbox — messages land in the recipient's NEXT turn via the mailbox-inject hook (pull, not push). Use whenever the user wants sessions/agents to talk to each other. |
| argument-hint | [@name] <message> | (empty = read inbox) | list | who |
/msg — Inter-Session Mailbox
A persistent append-only bus so ANY Claude Code session can message ANY other —
not just Agent-Teams teammates, no tmux, no daemon. Backed by
~/.claude/scripts/kei-message.sh writing ~/.claude/mailbox/messages.jsonl.
The mailbox-inject.sh UserPromptSubmit hook pulls each session's unread into
its context once per turn, so delivery is pull (arrives on the recipient's
next turn), not instant push.
Identity model
- Your address = the basename of this session's working directory (
$PWD).
So a session running in ~/Projects/frontend is reachable as @frontend.
all is the broadcast channel — every session sees to:"all" messages.- You can override the sender with
--from <name> and the reader identity with
--me <name> if a session's cwd basename isn't the name you want to use.
Command map
Interpret $ARGUMENTS and run the matching command via Bash, then show its
output to the user. The launcher kei message … and the script path are
equivalent — prefer the script path (always present after install):
| User typed | Run |
|---|
/msg (no args) | ~/.claude/scripts/kei-message.sh inbox |
/msg @frontend ship it | ~/.claude/scripts/kei-message.sh send @frontend ship it |
/msg all standup in 5 | ~/.claude/scripts/kei-message.sh send all standup in 5 |
/msg list | ~/.claude/scripts/kei-message.sh list |
/msg who (or channels) | ~/.claude/scripts/kei-message.sh channels |
Rules for parsing $ARGUMENTS:
- Empty → read inbox (
inbox). Show the messages addressed to this
session or to all.
- Starts with
@<name> → send to that recipient; the rest is the body.
A @x that appears later in the body stays literal text.
- Starts with
all → broadcast; the rest is the body.
list → print the recent whole bus (every from→to line).who / channels → print known recipient names (use this to discover
who is reachable before sending the first message).- Anything else with no leading
@/all → treat as a broadcast body, OR ask
the user who the recipient is if it's ambiguous.
Discovery (first-message problem)
A recipient only appears in who after it has sent or been sent a message, so
for the very first contact either broadcast with all, or ask the user for the
target session's cwd-basename. Don't invent a recipient name.
Notes
- Sending never blocks and never notifies the recipient out-of-band — they see
it on their next turn. For a time-sensitive ping, tell the user it's queued.
- This is plain files:
cat ~/.claude/mailbox/messages.jsonl is the raw bus.
- Bypass the inject hook for a session with
KEI_MAILBOX_BYPASS=1.
