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".

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

Format output as:

# Agent Mail Inbox

**Agent:** <agent-name>
**Project:** <project-key>
**Checked:** <timestamp>

## Pending Messages (<count>)

| From | Subject | Thread | Age |
|------|---------|--------|-----|
| ... | ... | ... | ... |

## HELP_REQUESTs Needing Response (<count>)

| From | Issue | Problem | Waiting |
|------|-------|---------|---------|
| demigod-gt-123 | gt-123 | STUCK - Can't find auth module | 15m |
| ... | ... | ... | ... |

## Recent Completions (<count>)

| Agent | Issue | Status | Completed |
|-------|-------|--------|-----------|
| demigod-gt-124 | gt-124 | DONE | 2m ago |
| ... | ... | ... | ... |

## Actions Needed

- [ ] Respond to HELP_REQUEST from demigod-gt-123 (waiting 15m)
- [ ] Acknowledge completion of gt-124

Watch Mode

When --watch flag is provided:

Step W1: Enter Polling Loop

POLL_INTERVAL=30  # seconds

while true; do
    clear
    echo "=== Agent Mail Inbox (Watch Mode) ==="
    echo "Press Ctrl+C to exit"
    echo ""

    # Execute Steps 3-7 above

    # Show last update time
    echo ""
    echo "Last updated: $(date)"
    echo "Next refresh in ${POLL_INTERVAL}s"

    sleep $POLL_INTERVAL
done

Step W2: Alert on New Messages

When new messages arrive since last poll:

# Compare message counts
if [ "$NEW_COUNT" -gt "$PREV_COUNT" ]; then
    echo "*** NEW MESSAGES ($((NEW_COUNT - PREV_COUNT))) ***"
    # Optionally use terminal bell
    echo -e "\a"
fi

# Highlight urgent HELP_REQUESTs
if [ "$HELP_WAITING_MINS" -gt 5 ]; then
    echo "*** URGENT: HELP_REQUEST waiting ${HELP_WAITING_MINS}m ***"
fi

Step W3: Show Message Summaries

For each new message, display summary:

---
**NEW:** From demigod-gt-125 | Thread: gt-125 | 10s ago
Subject: PROGRESS
> Step 4 in progress. Files touched: src/auth.py, tests/test_auth.py
---

MCP Tool Reference

Tool	Purpose
fetch_inbox	Get messages for agent
search_messages	Find messages by query
summarize_thread	Summarize a thread
acknowledge_message	Mark message as read

HTTP Fallback

If MCP tools unavailable but HTTP server running:

# Fetch inbox via HTTP
curl -s "http://localhost:8765/mcp/" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "fetch_inbox",
    "params": {
      "project_key": "<project-key>",
      "agent_name": "<agent-name>"
    }
  }'

# Search messages
curl -s "http://localhost:8765/mcp/" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "search_messages",
    "params": {
      "project_key": "<project-key>",
      "query": "HELP_REQUEST"
    }
  }'

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

Integration Points

System	Integration
Beads	Thread IDs often match beads issue IDs (e.g., gt-123)
Demigod	Demigods send progress, help requests, completions
Mayor	Mayor monitors inbox for coordination decisions
Chiron	Chiron watches for HELP_REQUESTs to answer

Example Session

# Quick check
/inbox

# Output:
# Agent Mail Inbox
# Agent: boden
# Project: /Users/fullerbt/gt/olympus
#
# Pending Messages (2)
# - PROGRESS from demigod-ol-527 (5m ago)
# - HELP_REQUEST from demigod-ol-528 (2m ago)
#
# HELP_REQUESTs Needing Response (1)
# - demigod-ol-528: STUCK - Can't find skill template format
#
# Actions Needed:
# - [ ] Respond to HELP_REQUEST from demigod-ol-528

# Start monitoring
/inbox --watch

Without Agent Mail

If Agent Mail is not available:

Agent Mail not available.

To enable:
1. Start MCP Agent Mail server:
   cd ~/gt/acfs-research/tier1/mcp_agent_mail
   uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765

2. Add to ~/.claude/mcp_servers.json:
   {
     "mcp-agent-mail": {
       "type": "http",
       "url": "http://127.0.0.1:8765/mcp/"
     }
   }

3. Restart Claude Code session