inbox

```bash

/inbox # Show current inbox state

/inbox --watch # Continuous polling mode

```

Given /inbox [--watch]:

Step 1: Check Agent Mail Availability

```bash

# 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

```bash

# 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: ""

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

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

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

thread_id: ""

```

Step 7: Display Results

Format output as:

```markdown

# Agent Mail Inbox

Agent:

Project:

Checked:

| From | Subject | Thread | Age |

|------|---------|--------|-----|

| ... | ... | ... | ... |

| From | Issue | Problem | Waiting |

|------|-------|---------|---------|

| demigod-gt-123 | gt-123 | STUCK - Can't find auth module | 15m |

| ... | ... | ... | ... |

| Agent | Issue | Status | Completed |

|-------|-------|--------|-----------|

| demigod-gt-124 | gt-124 | DONE | 2m ago |

| ... | ... | ... | ... |

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

```

When --watch flag is provided:

Step W1: Enter Polling Loop

```bash

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:

```bash

# 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:

```markdown

---

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

---

```

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

If MCP tools unavailable but HTTP server running:

```bash

# Fetch inbox via HTTP

curl -s "http://localhost:8765/mcp/" \

-H "Content-Type: application/json" \

-d '{

"method": "fetch_inbox",

"params": {

"project_key": "",

"agent_name": ""

}

}'

# Search messages

curl -s "http://localhost:8765/mcp/" \

-H "Content-Type: application/json" \

-d '{

"method": "search_messages",

"params": {

"project_key": "",

"query": "HELP_REQUEST"

}

}'

```

• 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

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

```bash

# 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

```

If Agent Mail is not available:

```markdown

Agent Mail not available.

To enable:

1. Start MCP Agent Mail server:

Start your Agent Mail MCP server (implementation-specific). See docs/agent-mail.md.

1. Add to ~/.claude/mcp_servers.json:

{

"mcp-agent-mail": {

"type": "http",

"url": "http://127.0.0.1:8765/mcp/"

}

}

1. Restart Claude Code session

```

---

• 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