* 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>
125 lines
3.8 KiB
Markdown
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
|