Send messages between agents to coordinate work, share context, and trigger actions. Messages arrive instantly during an agent’s turn or wake idle agents immediately.
Basic Messaging
Send to a Specific Agent
hcom send @luna -- Hello there!
-- is the message text (no quotes needed).
Send to Multiple Agents
hcom send @luna @nova -- Review this PR
Broadcast to All
hcom send -- Everyone, the build is broken
Messages are delivered instantly if the agent is active, or appear immediately when they resume work.
Message Sources
Inline Text (Default)
hcom send @luna -- This is my message
From Stdin
echo "Complex message with special chars" | hcom send @luna
hcom send @luna <<'EOF'
Multi-line message
with special chars
EOF
From File
hcom send @luna --file report.txt
From Base64
hcom send @luna --base64 "aGVsbG8gd29ybGQ="
Message Intents
Specify the type of message to set expectations:
Request
Expect a response:
hcom send @luna --intent request -- Can you help with this bug?
hcom send @luna --intent inform -- Build completed successfully
Ack (Acknowledgment)
Replying to a request:
hcom send @luna --intent ack --reply-to 42 -- Done, fixed the bug
When you send a request to another agent, hcom automatically creates a subscription to notify you when they go idle or stop, so you know when your request has been processed.
Threading
Group related messages in threads:
hcom send @luna --thread pr-123 -- Starting review
hcom send @nova --thread pr-123 -- Can you check auth changes?
Reply Chains
Reply to specific messages:
# Luna receives message #42
hcom send @luna --reply-to 42 -- Fixed the issue
Target Matching
hcom supports flexible agent targeting:
Exact Match
hcom send @api-luna -- message
Base Name Match
hcom send @luna -- message
# Matches: luna, api-luna, test-luna
hcom send @api- -- message to all api agents
# Matches all agents with 'api' tag
Remote Agents (Cross-Device)
hcom send @luna:BOXE -- message to luna on another device
Underscore blocks prefix matching: @luna does NOT match luna_reviewer_1
External Senders
Send messages as an external identity:
hcom send @luna --from reviewer -- Code looks good
hcom send @luna -b -- Quick message from bigboss
- Scripts and automation
- External monitoring systems
- Manual coordination
External senders don’t receive replies via hcom. Use this for one-way notifications.
Bundling Context
Attach structured context (transcript, events, files) inline:
hcom send @luna \
--title "Auth Bug Analysis" \
--description "Context for the authentication bug" \
--transcript "10-15:normal" \
--events "100-105" \
--files "src/auth.py,tests/test_auth.py" \
-- Please review this context and suggest a fix
Message Delivery
Messages are delivered based on scope:
Broadcast (No Targets)
Delivered to all registered agents:
hcom send -- Important announcement
Mentions (With Targets)
Delivered only to mentioned agents:
hcom send @luna @nova -- This is just for you two
Smart @Mentions in Text
Agents mentioned in the message text automatically receive it:
hcom send @luna -- Can you work with @nova on this?
# Delivered to both luna and nova
Practical Examples
Coordinate Parallel Work
hcom 3 claude --tag workers -p "process logs"
hcom send @workers -- Split the work: each take one server
Request Review
hcom send @reviewer --intent request --thread pr-456 -- \
Review auth changes in src/auth.py
Share Results
hcom send @lead --intent inform -- \
Tests passing: 127/127. Build ready for deploy.
Acknowledge Completion
hcom send @requester --intent ack --reply-to 99 -- \
Bug fixed and deployed
Reading Messages
From within an agent:
hcom listen # Wait for next message
hcom events --wait --type message # More flexible
Message Collisions
If two agents edit the same file within 30 seconds, both get notified:
[hcom-events] File collision detected:
luna edited src/db.py @ 10:32:15
nova edited src/db.py @ 10:32:30
hcom config auto_subscribe "collision"
Troubleshooting
Message Not Delivered
Check if target is registered:
Agent Not Responding
Check their status:
Check if they received it:
hcom events --from self --type message --last 5
Complex Message Parsing
Use -- separator to avoid flag confusion:
hcom send @luna -- --this-looks-like-a-flag but it's actually the message
Best Practices
- Use —intent request when you expect a response
- Use —intent inform for status updates
- Use —thread to group related conversations
- Use —from for external automation
- Use @mentions liberally - agents can see who else is involved
Don’t send sensitive data (credentials, secrets) via messages - they’re logged in plaintext in the events database.
Next Steps