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