Publish - Send Inter-Agent Messages

Send messages to other agents, broadcast to multiple sessions, or publish notifications to topic-based channels.

When to Use

• Handing off work to another agent
• Notifying other sessions of events or status
• Broadcasting updates to multiple agents
• Sending results or data to waiting agents
• Coordinating distributed work across sessions

How It Works

Messages are published to named topics. The sender is auto-detected from the current hive session context. Each message includes sender ID, timestamp, content, and topic(s).

Output: JSON confirmation line with status, resolved topics, and sender.

Commands

Publish with -m Flag (Recommended)

hive msg pub --topic <topic> -m "message content"

Examples:

# Send to specific agent's inbox
hive msg pub --topic agent.abc123.inbox -m "Task completed, ready for review"

# Send to multiple topics
hive msg pub -t agent.123.inbox -t agent.456.inbox -m "Important update"

Publish from Stdin

echo "Status update" | hive msg pub --topic notifications
cat report.txt | hive msg pub --topic reports

Publish from File

hive msg pub --topic agent.abc.inbox -f handoff-context.md

Publish with Positional Argument

hive msg pub --topic <topic> "message content"

Note: Prefer -m over positional args to avoid flag collision with single-character messages.

Broadcast with Wildcards

# Broadcast to all agent inboxes
hive msg pub -t "agent.*.inbox" -m "System maintenance in 5 minutes"

Wildcard * matches any characters within a segment. Topics are expanded at publish time.

Message Sources

Only one source may be used per publish:

• -m / --message flag (recommended)
• Positional argument
• -f / --file flag
• Stdin (default when no other source)

An error is returned if multiple sources are provided.

Topic Patterns

Standard Inbox Format

Agent inboxes follow: agent.<session-id>.inbox

# Find session IDs
hive ls

# Send to specific agent
hive msg pub --topic agent.abc123.inbox -m "Message"

Custom Topics

Create any topic name for specific use cases:

hive msg pub --topic deploy.started -m "Deployment initiated"
hive msg pub --topic build.events -m "Test suite running"

Topic Naming Conventions

• agent.<id>.inbox - Direct messages to agents
• <domain>.<event> - Event notifications (build.started, test.failed)
• <feature>.<channel> - Feature-specific channels

Avoid generic names, special characters besides ., -, _.

Common Workflows

Hand Off Work

# Complete work and notify next agent
hive msg pub --topic agent.xyz789.inbox -m "Auth implementation complete. See PR #123. Tests passing."

Notify Multiple Topics

hive msg pub \
  -t agent.abc.inbox \
  -t agent.xyz.inbox \
  -t coordinator.updates \
  -m "Feature X ready for review"

Send Command Output

go test -v ./... | hive msg pub --topic test.results

Override Sender ID

hive msg pub --topic test.channel --sender "custom-agent-id" -m "Test message"

Additional Resources

For troubleshooting, advanced patterns, and coordination workflows, see:

• references/troubleshooting.md - Common issues and solutions

Related Skills

• /hive:inbox - Check inbox for messages
• /hive:wait - Wait for messages with timeout
• /hive:session-info - Get session details and inbox topic