beads/engdocs/messaging.md
swedeinasia-flow 857723a17a
fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829)
* fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup'

The Large Database check, its agent enrichment, the stale-closed-issues
enrichment, the Dolt perf recommendations, and the doctor --fix advisory
all told users to run 'bd cleanup', which is not a root-level command in
this build (cleanup lives under 'bd admin cleanup'). The operator-facing
lifecycle command is 'bd prune', whose --older-than flag takes durations
like 90d and which previews by default (--force to delete) — a better fit
for advice the doctor explicitly refuses to auto-fix because it deletes
data.

Extract largeDatabaseWarning so the remedy string is pinned by a test,
and pin the two enrichments' command lists likewise.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(messaging): replace stale ephemeral cleanup commands

Update the remaining live messaging examples to use the current wisp-scoped bd purge command and duration syntax.

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Klas Hesselman

---------

Co-authored-by: Klas Hesselman <211416696+swedeinasia-flow@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-20 05:30:47 -07:00

125 lines
3.8 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 purge --force
# Preview what would be deleted
bd purge --dry-run
# Only delete ephemeral messages older than 7 days
bd purge --older-than 7d --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.
Creates with initial labels preserve the legacy hook sequence: `on_create` receives the issue snapshot before labels, followed by one or more `on_update` events with cumulative label snapshots. The labels are already persisted before those hooks run, so hook scripts that need the create-time sequence should rely on the JSON payload instead of re-reading the issue from the store during the hook.
Batch creates with initial dependencies emit `on_update` for each persisted
dependency after the create-time hooks. Each payload carries a cumulative
dependency snapshot in request order, matching the event shape produced by
explicit post-create dependency additions; dependencies skipped because their
target was not persisted do not produce hooks.
## See Also
- [Graph Links](../docs/core-concepts/graph-links.md) - relates_to, duplicates, supersedes, replies_to
- [CLI Reference](../docs/CLI_REFERENCE.md) - All commands