How do I install the Inbox skill?

Run npx skillmds@latest add colonyops/inbox in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Inbox safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Inbox?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Inbox free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

colonyops (@colonyops) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Inbox by colonyops — Agent Skill

Name: Inbox
Author: colonyops

Inbox

This skill should be used when the user asks to "check my inbox", "read my messages", "any unread messages?", "check for new messages", "see my inbox", or needs to read inter-agent messages from other hive sessions. Provides guidance on reading, filtering, and managing inbox messages.

colonyops 397c592 2 files · 4.0 KB Updated Sep 17, 2026

File contents

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 identifier
topic - The inbox topic (agent.<id>.inbox)
payload - The message text
sender - 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
hive hc 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

---name: inboxdescription: This skill should be used when the user asks to "check my inbox", "read my messages", "any unread messages?", "check for new messages", "see my inbox", or needs to read inter-agent messages from other hive sessions. Provides guidance on reading, filtering, and managing inbox messages.---# Inbox - Read Inter-Agent MessagesCheck 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 WorksEach 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)```bashhive msg inbox```Shows unread messages without marking them as read.### Read and Acknowledge```bashhive msg inbox --ack```Shows unread messages and marks them as read so they won't appear again.### Read All Messages```bashhive msg inbox --all```Shows all messages (read and unread).### Specify Session Explicitly```bashhive msg inbox --session <id|name>```Overrides auto-detection from working directory. Useful when running outside a session directory.### Wait for a Message```bashhive msg inbox --waithive msg inbox --wait --timeout 2m```Blocks until a message arrives. Default timeout is 24h for wait mode.### Poll for New Messages```bashhive msg inbox --listen --timeout 30s```Continuously polls and outputs new messages until timeout.### Limit Results```bashhive msg inbox --tail 5```Returns only the last N unread messages.## Output FormatAll output is JSON Lines (one JSON object per line) on stdout. Fields:- `id` - Unique message identifier- `topic` - The inbox topic (`agent.<id>.inbox`)- `payload` - The message text- `sender` - Who sent the message (session ID or custom sender)- `session_id` - Sender's session ID (if auto-detected)- `created_at` - ISO 8601 timestampOn timeout (`--listen`/`--wait`), a JSON status line is printed and exit code is 1.## Common Workflows### Basic Message Check```bashhive msg inbox```Read and act on any unread messages.### Handle Coordinated HandoffWhen another agent hands off work:```bash# Check inbox for handoff messagehive msg inbox# Read referenced task detailshive hc show <issue-id>```### Review Message History```bashhive msg inbox --all```## Additional ResourcesFor 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

Frequently asked questions