> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging

> Agent communication — send, broadcast, inbox, chat.

# Messaging Commands

PG-backed messaging commands between agents. Replaces file-based mailbox with PostgreSQL conversations and messages tables.

## Messaging at a Glance

<Frame>
  <CodeGroup>
    ```bash Send Messages theme={"dark"}
    $ genie send 'Implement the API endpoints from Group 1' --to engineer
    Message sent to engineer.
      Conversation: DM with engineer
      Timestamp: 2026-03-24T14:30:00Z

    $ genie send 'Group 1 complete — all criteria met' --to team-lead
    Message sent to team-lead.
      Conversation: DM with team-lead
      Timestamp: 2026-03-24T14:45:00Z
    ```

    ```bash Check Inbox theme={"dark"}
    $ genie inbox
    CONVERSATION          LAST MESSAGE                              TIME
    DM: team-lead        "Starting Wave 2 — Groups 3,4 unblocked"  1m ago
    DM: engineer          "Group 1 complete — all criteria met"      15m ago
    Team: auth-fix        "Wave 1 complete. Starting Wave 2."        16m ago
    ```

    ```bash Broadcast & Chat theme={"dark"}
    $ genie broadcast 'Wave 1 complete. Starting Wave 2.'
    Broadcast to team "auth-fix":
      Message: Wave 1 complete. Starting Wave 2.
      Recipients: team-lead, engineer, reviewer

    $ genie chat list --team auth-fix
    CONVERSATION          TYPE    MESSAGES   LAST ACTIVITY
    auth-fix              team    42         1m ago
    DM: team-lead         dm      12         5m ago
    DM: engineer          dm      8          15m ago
    Thread: #msg-201      thread  3          20m ago
    ```
  </CodeGroup>
</Frame>

## `genie send`

Send a direct message to a specific agent via PG conversation.

```bash theme={"dark"}
genie send '<message>' [options]
```

| Flag              | Description                                           | Default     |
| ----------------- | ----------------------------------------------------- | ----------- |
| `--to <agent>`    | Recipient agent name                                  | `team-lead` |
| `--from <sender>` | Sender ID (auto-detected from context)                | —           |
| `--team <name>`   | Explicit team context for sender/recipient resolution | —           |

```bash Terminal theme={"dark"}
$ genie send 'Group 1 complete — all criteria met' --to team-lead
Message sent to team-lead.
  Conversation: DM with team-lead
  Timestamp: 2026-03-24T14:30:00Z

$ genie send 'Starting wave 2' --to engineer --from reviewer --team auth-rewrite
Message sent to engineer.
```

### Sender Identity Detection

The sender is auto-detected using this cascade:

1. `GENIE_AGENT_NAME` env var (explicit override)
2. `TMUX_PANE` → agent registry lookup
3. `TMUX_PANE` → native team config match
4. Fallback: `cli`

## `genie broadcast`

Send a message to the team conversation.

```bash theme={"dark"}
genie broadcast '<message>' [options]
```

| Flag              | Description                            |
| ----------------- | -------------------------------------- |
| `--from <sender>` | Sender ID (auto-detected from context) |
| `--team <name>`   | Team name (auto-detected from context) |

```bash Terminal theme={"dark"}
$ genie broadcast 'Wave 1 complete. Starting Wave 2.'
Broadcast to team "auth-rewrite":
  Message: Wave 1 complete. Starting Wave 2.
  Recipients: team-lead, engineer, reviewer

$ genie broadcast 'Deploying hotfix' --team auth-rewrite --from team-lead
Broadcast to team "auth-rewrite":
  Message: Deploying hotfix
  Recipients: engineer, reviewer, fixer
```

## `genie inbox`

Check agent inbox for recent messages.

### `genie inbox list`

List conversations with recent messages.

```bash theme={"dark"}
genie inbox list [options] [agent]
```

```bash Terminal theme={"dark"}
$ genie inbox list
CONVERSATION          LAST MESSAGE                              TIME
DM: team-lead        "Group 2 ready for review"                2m ago
DM: engineer          "Starting Group 3 implementation"         5m ago
Team: auth-rewrite    "Wave 1 complete. Starting Wave 2."       8m ago
```

### `genie inbox watch`

Watch for new messages in real-time.

```bash theme={"dark"}
genie inbox watch
```

## `genie chat`

Send to a specific conversation, create threads, or list conversations.

### Send to conversation

```bash theme={"dark"}
genie chat send <conversationId> '<message>'
```

### Read messages in a conversation

```bash theme={"dark"}
genie chat read [options] <conversationId>
```

### Create a thread

```bash theme={"dark"}
genie chat thread <message_id>
```

### List conversations

```bash theme={"dark"}
genie chat list [--team <name>] [--type dm|team|thread]
```

```bash Terminal theme={"dark"}
$ genie chat list --team auth-rewrite
CONVERSATION          TYPE    MESSAGES   LAST ACTIVITY
auth-rewrite          team    42         2m ago
DM: team-lead         dm      12         5m ago
Thread: #msg-123      thread  3          8m ago
```