beads/docs/messaging.md
garnet 3dae6bb3df refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8)
Replace gastown-specific references with generic alternatives throughout
the codebase:

- Rename --gastown flag to --orchestrator in bd doctor
- Rename gastownMode/gastownThreshold params to orchestratorMode/orchestratorThreshold
- Rename isGasTownTownRoot() to isOrchestratorRoot()
- Replace "gastown" in CLI examples with generic rig names (my-project, other-project)
- Update comments replacing "Gas Town" with "orchestrator" or "multi-agent workspace"
- Update active docs (DOLT.md, CONFIG.md, ADVANCED.md, etc.)
- Update test data to use generic names instead of "gastown"
- Update role templates (deacon, witness, refinery) to use generic language

Preserved as historical (not changed):
- CHANGELOG.md entries (historical record)
- ARTICLES.md (links to real published articles)
- info.go version notes (historical release notes)
- gastown/ file path references in dolt-concurrency.md (point to actual repo)
2026-03-20 18:39:50 -07:00

117 lines
3.1 KiB
Markdown

# Messaging in Beads
Beads supports messaging as a first-class issue type, enabling inter-agent and human-agent communication within the same system used for issue tracking.
## Architecture
Mail commands (`bd mail`) delegate to an external mail provider (typically `gt mail` in an orchestrator). Beads stores messages as issues with `type: message`, threading via `replies_to` dependencies, and ephemeral lifecycle via the `ephemeral` flag.
This design separates concerns:
- **Beads** = data plane (stores messages as issues)
- **Orchestrator** = control plane (routing, delivery, notifications)
## Setup
Configure the mail delegate (one-time):
```bash
# Environment variable (recommended for agents)
export BEADS_MAIL_DELEGATE="gt mail"
# Or per-project config
bd config set mail.delegate "gt mail"
```
## Sending and Receiving
```bash
# Send mail (delegates to gt mail)
bd mail send worker/ -s "Review needed" -m "Please review bd-abc"
# Check inbox
bd mail inbox
# Read a message
bd mail read msg-123
# Reply to a thread
bd mail reply msg-123 -m "Reviewed and approved"
```
## Message Issue Type
Messages are issues with `type: message`:
| Field | Purpose |
|-------|---------|
| `type` | `message` |
| `sender` | Who sent the message |
| `assignee` | Recipient |
| `title` | Subject line |
| `description` | Message body |
| `status` | `open` (unread) / `closed` (read) |
| `ephemeral` | If true, eligible for bulk cleanup |
## Threading
Messages form threads via `replies_to` dependencies. View a full thread:
```bash
bd show msg-123 --thread
```
This traces the `replies_to` chain to find the root message, then collects all replies via BFS, displaying the conversation with proper indentation.
Thread display shows:
- Sender and recipient
- Timestamp
- Subject and body
- Reply depth (indented)
## Ephemeral Messages
Messages marked `ephemeral: true` are transient - they can be bulk-deleted after a swarm completes:
```bash
# Clean up closed ephemeral messages
bd cleanup --ephemeral --force
# Preview what would be deleted
bd cleanup --ephemeral --dry-run
# Only delete ephemeral messages older than 7 days
bd cleanup --ephemeral --older-than 7 --force
```
Ephemeral messages are:
- Excluded from `bd ready` by default
- Not synced to remotes (transient)
- Eligible for bulk deletion when closed
## Identity
The actor identity (used for `sender` on messages) is resolved in order:
1. `--actor` flag on the command
2. `BEADS_ACTOR` environment variable
3. `BD_ACTOR` environment variable (deprecated alias)
4. `git config user.name`
5. `$USER` environment variable
6. `"unknown"`
## Beads Event Hooks
Scripts in `.beads/hooks/` run after certain events:
| Hook | Trigger |
|------|---------|
| `on_create` | After `bd create` |
| `on_update` | After `bd update` |
| `on_close` | After `bd close` |
Hooks receive event data as JSON on stdin. This enables orchestrator integration (e.g., notifying services of new messages) without beads knowing about the orchestrator.
## See Also
- [Graph Links](graph-links.md) - relates_to, duplicates, supersedes, replies_to
- [CLI Reference](CLI_REFERENCE.md) - All commands