beads/engdocs/messaging.md
Chris Sells 3198395a32 docs(ci): add Mintlify preview, docsync guard, and broken-links workflow
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
  (Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
  correspondence — every nav entry has a file, every page is in the nav
  (tiny stub allowlist for paths released bd binaries print), published
  pages use root-relative extensionless links that resolve, and engdocs/
  plus curated root markdown keep exact GitHub-style paths. Wired into
  make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
  mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
  mirrored files now live once in the Mintlify site; the committed
  Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
  npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
  pointer stub (bd's agent templates print that path). Runtime strings in
  cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
  old paths — covered by stubs, flagged in the PR.
2026-07-12 10:37:07 -07:00

3.8 KiB

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):

# 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

# 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:

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:

# 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.

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