inbox
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 (agent.<id>.inbox). Other agents publish messages to this inbox, readable via the commands below.
By default, messages are NOT marked as read. Use --ack to acknowledge messages.
Commands
Read Unread Messages (Default)
hive msg inbox
Shows unread messages without marking them as read.
Read and Acknowledge
hive msg inbox --ack
Shows unread messages and marks them as read so they won't appear again.
Read All Messages
hive msg inbox --all
Shows all messages (read and unread).
Specify Session Explicitly
hive msg inbox --session <id|name>
Overrides auto-detection from working directory. Useful when running outside a session directory.
Wait for a Message
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
hive msg inbox --listen --timeout 30s
Continuously polls and outputs new messages until timeout.
Limit Results
hive msg inbox --tail 5
Returns only the last N unread messages.
Output Format
All output is JSON Lines (one JSON object per line) on stdout. Fields:
id- Unique message identifiertopic- The inbox topic (agent.<id>.inbox)payload- The message textsender- Who sent the message (session ID or custom sender)session_id- Sender's session ID (if auto-detected)created_at- ISO 8601 timestamp
On timeout (--listen/--wait), a JSON status line is printed and exit code is 1.
Common Workflows
Basic Message Check
hive msg inbox
Read and act on any unread messages.
Handle Coordinated Handoff
When another agent hands off work:
# Check inbox for handoff message
hive msg inbox
# Read referenced task details
bd show <issue-id>
Review Message History
hive msg inbox --all
Additional Resources
For troubleshooting and advanced usage patterns, see:
references/troubleshooting.md- Common issues and solutions
Related Skills
/hive:publish- Send messages to other agents/hive:wait- Wait for specific messages with timeout/hive:session-info- Get current session details and inbox topic
More from colonyops/hive
tui-component-design
Best practices for building maintainable, testable TUI components using Bubbletea v2 and the Charm ecosystem. Covers component organization, state management, async operations, visual modes, and common pitfalls.
53tui-testing
Comprehensive testing strategies for Bubbletea v2 applications. Covers unit tests, component tests, golden file testing, async operations, external tool integration, and common testing pitfalls.
45config
This skill should be used when the user asks to "configure hive", "setup hive for my workflow", "customize session spawn", "add tmux integration", "create custom keybindings", "add user commands", or needs guidance on hive configuration, rules, spawn commands, terminal integration, or keybindings.
18docs-update
Update documentation after code changes. Use when adding features, changing keybindings, modifying config options, or updating TUI behavior. Automatically finds and updates relevant documentation files (README, recipes, help text).
16session-info
This skill should be used when the user asks "what's my session ID?", "show my inbox topic", "get session info", "what session am I in?", "my agent ID", or needs to retrieve current hive session details for messaging coordination or debugging.
16wait
This skill should be used when the user asks to "wait for message from agent X", "block until response", "wait for handoff", "synchronize with other agents", "wait for acknowledgment", or needs to block execution until messages arrive on specific topics with configurable timeout.
15