8d73a86f7a
- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9) - Add Ephemeral filter to IssueFilter type - Add ephemeral filtering to SQLite storage queries Tests (bd-kwro.10): - Add internal/hooks/hooks_test.go for hook system - Add cmd/bd/mail_test.go for mail commands - Add internal/storage/sqlite/graph_links_test.go for graph links Documentation (bd-kwro.11): - Add docs/messaging.md for full messaging reference - Add docs/graph-links.md for graph link types - Update AGENTS.md with inter-agent messaging section - Update CHANGELOG.md with all bd-kwro features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
5.4 KiB
5.4 KiB
Beads Messaging System
Beads provides a built-in messaging system for inter-agent communication. Messages are stored as beads issues with type message, enabling git-native communication without external services.
Overview
The messaging system enables:
- Agent-to-agent communication - Send messages between workers
- Thread tracking - Replies link back to original messages
- Priority signaling - Mark messages as urgent (P0) or routine
- Ephemeral cleanup - Messages can be bulk-deleted after completion
Identity Configuration
Before using mail commands, configure your identity:
Environment Variable
export BEADS_IDENTITY="worker-1"
Config File
Add to .beads/config.json:
{
"identity": "worker-1"
}
Priority
--identityflag (if provided)BEADS_IDENTITYenvironment variable.beads/config.jsonidentity field- System username (fallback)
Commands
Send a Message
bd mail send <recipient> -s <subject> -m <body>
Options:
-s, --subject- Message subject (required)-m, --body- Message body (required)--urgent- Set priority=0 (urgent)--identity- Override sender identity
Examples:
# Basic message
bd mail send worker-1 -s "Task complete" -m "Finished bd-xyz"
# Urgent message
bd mail send manager -s "Blocked!" -m "Need credentials for deploy" --urgent
# With custom identity
bd mail send worker-2 -s "Handoff" -m "Your turn on bd-abc" --identity refinery
Check Your Inbox
bd mail inbox
Lists all open messages addressed to your identity.
Options:
--from <sender>- Filter by sender--priority <n>- Filter by priority (0-4)
Output:
Inbox for worker-1 (2 messages):
bd-a1b2: Task assigned [URGENT]
From: manager (5m ago)
bd-c3d4: FYI: Design doc updated
From: worker-2 (1h ago)
Re: bd-x7y8
Read a Message
bd mail read <id>
Displays full message content. Does NOT mark as read.
Example output:
──────────────────────────────────────────────────────────────────
ID: bd-a1b2
From: manager
To: worker-1
Subject: Task assigned
Time: 2025-12-16 10:30:45
Priority: P0
Status: open
──────────────────────────────────────────────────────────────────
Please prioritize bd-xyz. It's blocking the release.
Let me know if you need anything.
Acknowledge (Mark as Read)
bd mail ack <id> [id2...]
Closes messages to mark them as acknowledged.
Examples:
# Single message
bd mail ack bd-a1b2
# Multiple messages
bd mail ack bd-a1b2 bd-c3d4 bd-e5f6
Reply to a Message
bd mail reply <id> -m <body>
Creates a threaded reply to an existing message.
Options:
-m, --body- Reply body (required)--urgent- Set priority=0--identity- Override sender identity
Behavior:
- Sets
replies_toto original message ID - Sends to original message's sender
- Prefixes subject with "Re:" if not already present
Example:
bd mail reply bd-a1b2 -m "On it! Should be done by EOD."
Message Storage
Messages are stored as issues with these fields:
| Field | Description |
|---|---|
type |
message |
title |
Subject line |
description |
Message body |
assignee |
Recipient identity |
sender |
Sender identity |
priority |
0 (urgent) to 4 (routine), default 2 |
ephemeral |
true - can be bulk-deleted |
replies_to |
ID of parent message (for threads) |
status |
open (unread) / closed (read) |
Cleanup
Messages are ephemeral by default and can be cleaned up:
# Preview ephemeral message cleanup
bd cleanup --ephemeral --dry-run
# Delete all closed ephemeral messages
bd cleanup --ephemeral --force
Hooks
The messaging system fires hooks when messages are sent:
Hook file: .beads/hooks/on_message
The hook receives:
- Arg 1: Issue ID
- Arg 2: Event type (
message) - Stdin: Full issue JSON
Example hook:
#!/bin/sh
# .beads/hooks/on_message
ISSUE_ID="$1"
EVENT="$2"
# Parse assignee from JSON stdin
ASSIGNEE=$(cat | jq -r '.assignee')
# Notify recipient (example: send to external system)
curl -X POST "https://example.com/notify" \
-d "to=$ASSIGNEE&message=$ISSUE_ID"
Make the hook executable:
chmod +x .beads/hooks/on_message
JSON Output
All commands support --json for programmatic use:
bd mail inbox --json
bd mail read bd-a1b2 --json
bd mail send worker-1 -s "Hi" -m "Test" --json
Thread Visualization
Use bd show --thread to view message threads:
bd show bd-c3d4 --thread
This shows the full conversation chain via replies_to links.
Best Practices
- Use descriptive subjects - Recipients scan subjects first
- Mark urgent sparingly - P0 should be reserved for blockers
- Acknowledge promptly - Keep inbox clean
- Clean up after sprints - Run
bd cleanup --ephemeralperiodically - Configure identity - Use
BEADS_IDENTITYfor consistent sender names
See Also
- Graph Links - Other link types (relates_to, duplicates, supersedes)
- Hooks - Custom hook scripts
- Config - Configuration options