Inbox - Read Inter-Agent Messages
Check and read messages sent to this session's inbox from other agents or sessions.
When to Use
- Another agent mentions sending a message
- Starting work on a task that may have been handed off
- Coordinating with other Claude sessions
- Checking for pending messages or recent communications
How It Works
Each hive session has a unique inbox topic (
). Other agents publish messages to this inbox, readable via the commands below.
By default, messages are NOT marked as read. Use
to acknowledge messages.
Commands
Read Unread Messages (Default)
Shows unread messages without marking them as read.
Read and Acknowledge
Shows unread messages and marks them as read so they won't appear again.
Read All Messages
Shows all messages (read and unread).
Specify Session Explicitly
bash
hive msg inbox --session <id|name>
Overrides auto-detection from working directory. Useful when running outside a session directory.
Wait for a Message
bash
hive msg inbox --wait
hive msg inbox --wait --timeout 2m
Blocks until a message arrives. Default timeout is 24h for wait mode.
Poll for New Messages
bash
hive msg inbox --listen --timeout 30s
Continuously polls and outputs new messages until timeout.
Limit Results
Returns only the last N unread messages.
Output Format
All output is JSON Lines (one JSON object per line) on stdout. Fields:
- - Unique message identifier
- - The inbox topic ()
- - The message text
- - Who sent the message (session ID or custom sender)
- - Sender's session ID (if auto-detected)
- - ISO 8601 timestamp
On timeout (
/
), a JSON status line is printed and exit code is 1.
Common Workflows
Basic Message Check
Read and act on any unread messages.
Handle Coordinated Handoff
When another agent hands off work:
bash
# Check inbox for handoff message
hive msg inbox
# Read referenced task details
bd show <issue-id>
Review Message History
Additional Resources
For troubleshooting and advanced usage patterns, see:
references/troubleshooting.md
Related Skills
- - Send messages to other agents
- - Wait for specific messages with timeout
- - Get current session details and inbox topic