inbox

# /inbox

> Point-to-point messaging between agents.

## Purpose

The communication backbone for multi-agent coordination. Every agent has an inbox directory. Messages are JSON files written atomically (write to temp, then rename — no partial reads). Supports direct messages, broadcasts, and reply chains. Full event log for debugging coordination issues.

## Usage

```bash
# Send a message to an agent
/inbox send researcher "Found the pricing data — check money-revenue/context.md"

# Broadcast to all agents
/inbox broadcast "Standup in 5 minutes — report your status"

# Check your inbox
/inbox receive

# Peek at an agent's inbox (read without consuming)
/inbox peek researcher

# Check inbox with filter
/inbox receive --type task --unread

# View message history
/inbox log --last 20

# Reply to a message
/inbox reply msg-a1b2c3 "Acknowledged, starting now"

# Clear processed messages
/inbox clear --before 2026-03-19
```

## Arguments

| Subcommand | Description |
|------------|-------------|
| `send <target> <message>` | Send a direct message to a specific agent |
| `broadcast <message>` | Send to all registered agents |
| `receive` | Read and consume messages from your inbox |
| `peek <target>` | Read an agent's inbox without consuming |
| `reply <msg-id> <message>` | Reply to a specific message (maintains thread) |
| `log` | View message event log |
| `clear` | Remove processed messages |

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--type` | enum | `all` | Filter: `task`, `status`, `result`, `error`, `info` |
| `--unread` | flag | false | Only show unread messages |
| `--last` | int | 10 | Number of log entries to show |
| `--before` | date | — | Clear messages before this date |
| `--format` | enum | `pretty` | `pretty`, `json`, `raw` |
| `--priority` | enum | `normal` | Message priority: `urgent`, `normal`, `low` |
| `--thread` | string | — | Thread ID to filter by |

## Workflow

### Sending
1. **Resolve target** — Look up agent by name or ID in the registry. Verify agent is running.
2. **Compose message** — Create JSON envelope: `{id, from, to, type, priority, thread, timestamp, body}`.
3. **Atomic write** — Write to temp file in target's inbox dir, then `rename()` to final path. This guarantees no partial reads.
4. **Log** — Append send event to the shared event log.
5. **Acknowledge** — Return message ID and delivery confirmation.

### Receiving
1. **Scan inbox** — List all `.json` files in own inbox directory, sorted by timestamp.
2. **Filter** — Apply type, unread, and priority filters.
3. **Read** — Parse and display messages. Mark as read (rename with `.read` suffix or move to `processed/`).
4. **Return** — Display messages in requested format.

## Output

### Send confirmation
```
Message sent: msg-2026-03-20-143500-a1b2
  To: researcher
  Type: info
  Priority: normal
  Thread: new
```

### Receive output
```markdown
## Inbox (3 unread)

### 1. From: orchestrator | 14:30 | urgent | task
> Analyze Q1 revenue data and produce summary by EOD.
> Context: money-revenue/context.md, money-revenue/signals/q1-*.md
> Reply to: msg-2026-03-20-143000-d4e5

### 2. From: writer | 14:32 | normal | info
> Draft pitch deck is ready for review at processed/pitch-v1.md

### 3. From: analyst | 14:35 | normal | result
> Revenue analysis complete. Key finding: 23% MoM growth.
> Full report: processed/q1-revenue-report.md
```

### Message JSON format
```json
{
  "id": "msg-2026-03-20-143500-a1b2",
  "from": "orchestrator",
  "to": "researcher",
  "type": "task",
  "priority": "urgent",
  "thread": "thread-revenue-analysis",
  "timestamp": "2026-03-20T14:35:00Z",
  "body": "Analyze Q1 revenue data and produce summary by EOD.",
  "context": ["money-revenue/context.md"],
  "reply_to": null
}
```

## Dependencies

- Agent registry (for resolving agent names to inbox paths)
- File system with atomic rename support
- Shared event log file (append-only)