inbox

name	inbox
description	Agent Mail inbox monitoring. Check pending messages, HELP_REQUESTs, and recent completions. Triggers: "inbox", "check mail", "any messages", "show inbox", "pending messages", "who needs help".
allowed-tools	Read, Grep, Glob, Bash
model	haiku
metadata	{"tier":"session","dependencies":[]}

Inbox Skill

Quick Ref: Monitor Agent Mail from any session. View pending messages, help requests, completions.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Monitor Agent Mail messages for coordination across agents.

Requires: MCP Agent Mail tools OR HTTP endpoint at localhost:8765.

Invocation

/inbox              # Show current inbox state
/inbox --watch      # Continuous polling mode

Execution Steps

Given /inbox [--watch]:

Step 1: Check Agent Mail Availability

# Check if Agent Mail MCP tools are available
# Look for tools starting with mcp__mcp-agent-mail__

# Alternatively, check HTTP endpoint
curl -s http://localhost:8765/health 2>/dev/null && echo "Agent Mail HTTP available" || echo "Agent Mail not running"

Step 2: Determine Agent Identity

# Check environment for agent identity
if [ -n "$OLYMPUS_DEMIGOD_ID" ]; then
    AGENT_NAME="$OLYMPUS_DEMIGOD_ID"
elif [ -n "$AGENT_NAME" ]; then
    AGENT_NAME="$AGENT_NAME"
else
    # Default to asking or using hostname
    AGENT_NAME="${USER:-unknown}-$(hostname -s 2>/dev/null || echo local)"
fi

# Get project key (current repo path)
PROJECT_KEY=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "Agent: $AGENT_NAME"
echo "Project: $PROJECT_KEY"

Step 3: Fetch Inbox (MCP Method)

Use MCP tool if available:

Tool: mcp__mcp-agent-mail__fetch_inbox
Parameters:
  project_key: "<project-key>"
  agent_name: "<agent-name>"

Parse results into categories:

• Pending: Messages without acknowledgement
• HELP_REQUEST: Messages with subject containing "HELP_REQUEST"
• Completions: Messages with subject "OFFERING_READY" or "DONE"

Step 4: Search for HELP_REQUESTs Needing Response

Search for unresolved help requests:

Tool: mcp__mcp-agent-mail__search_messages
Parameters:
  project_key: "<project-key>"
  query: "HELP_REQUEST"

Filter to those without HELP_RESPONSE in same thread.

Step 5: Get Recent Completions

Search for done messages:

Tool: mcp__mcp-agent-mail__search_messages
Parameters:
  project_key: "<project-key>"
  query: "OFFERING_READY OR DONE OR COMPLETED"

Step 6: Summarize Threads (Optional)

For active threads with multiple messages:

Tool: mcp__mcp-agent-mail__summarize_thread
Parameters:
  project_key: "<project-key>"
  thread_id: "<thread-id>"

Step 7: Display Results

Read references/output-format.md for the display template and example session.

Watch Mode

Read references/watch-mode.md for watch mode polling loop, alerting, and message summaries.

Transport Details

Read references/transport-reference.md for MCP tool reference, HTTP fallback, and setup instructions.

Key Rules

• Check regularly - Agents may be waiting for help
• Prioritize HELP_REQUESTs - Blocked agents waste resources
• Acknowledge completions - Closes the coordination loop
• Use watch mode - For active orchestration sessions

---

Examples

Checking Inbox During Active Work

User says: /inbox

What happens:

1. Agent checks for MCP Agent Mail tools, finds them available
2. Agent determines identity from $AGENT_NAME or hostname, gets project key from git
3. Agent fetches inbox using MCP tool, finds 3 pending messages
4. Agent searches for HELP_REQUESTs, finds 1 unresolved request from worker-2
5. Agent gets recent completions, finds 2 OFFERING_READY messages
6. Agent displays formatted results showing pending help request and recent completions
7. Agent suggests: "Worker-2 needs help with database schema migration"

Result: Inbox shows 1 critical help request requiring attention and 2 completed tasks.

Watch Mode for Orchestration

User says: /inbox --watch

What happens:

1. Agent enters polling loop checking inbox every 30 seconds
2. Agent displays initial state: 0 pending, 0 help requests
3. After 2 minutes, new HELP_REQUEST appears from worker-5
4. Agent alerts user with notification and message summary
5. Agent continues watching, detects OFFERING_READY from worker-3
6. Agent maintains live display of inbox state until user interrupts

Result: Continuous monitoring mode catches new help requests in real-time for quick response.

Troubleshooting

Problem	Cause	Solution
"Agent Mail not running" error	MCP server not started or HTTP endpoint down	Start Agent Mail server: check MCP config or run standalone server on localhost:8765. Verify with curl http://localhost:8765/health.
Empty inbox despite active workers	Wrong agent name or project key	Verify $AGENT_NAME matches worker expectations. Check project key with git rev-parse --show-toplevel. Use absolute path, not relative.
HELP_REQUESTs not showing	Missing search or filter issue	Verify search query includes "HELP_REQUEST" string. Check message subjects match protocol. Use search_messages tool to debug.
Watch mode exits immediately	Polling error or missing dependency	Check MCP tools work individually first. Verify --watch flag parsing. Fall back to manual polling: run /inbox repeatedly instead of --watch.

References

• Agent Mail Protocol: See skills/shared/agent-mail-protocol.md for message format specifications
• Parser (Go): cli/internal/agentmail/ - shared parser for all message types