Skip to main content

​
Overview

Block until a message arrives or an event matches filters. Used by agents to receive messages and by scripts to wait for specific conditions.

​
Basic Usage

# Wait for messages (24h timeout)
hcom listen

# Wait with 5 second timeout
hcom listen 5

# Quick check for unread messages (0.1s timeout)
hcom listen 1

​
Timeout

​
timeout
number
default:"86400"
Timeout in seconds (positional or --timeout flag)Default: 86400 seconds (24 hours)
hcom listen 60        # 60 second timeout
hcom listen --timeout 300   # 5 minute timeout
Quick check mode: Timeout ≤ 1 second becomes 0.1s poll

​
Output Formats

​
--json
boolean
Output messages as JSON (one per line)
hcom listen --json
Output format:
{"from": "luna", "text": "message content"}

​
Default Output

Human-readable format with intent/thread context: 
[request #42] luna → nova: Can you review PR #99?

[inform:standup] kira → all: Daily update complete

[3 new messages] | [request #50] luna → nova: msg1 | [inform] kira → nova: msg2

​
Filter Mode

Wait for events matching filter conditions. Supports all hcom events filter flags:

​
Event Type Filters

​
--type
string
Event type: message, status, life
hcom listen --type message --timeout 30
hcom listen --type status --agent luna
​
--agent
string
Filter by agent name
hcom listen --agent luna --timeout 60

​
Message Filters

​
--from
string
Message sender name
hcom listen --from luna --timeout 30
​
--mention
string
Messages mentioning target
hcom listen --mention @nova
​
--intent
enum
Message intent: request, inform, ack
hcom listen --intent request
​
--thread
string
Thread name
hcom listen --thread pr-99

​
Status Filters

​
--status
enum
Agent status: listening, active, blocked, inactive
hcom listen --status blocked
​
--context
string
Status context (supports wildcard *)
hcom listen --context "tool:Bash"
hcom listen --context "deliver:*"

​
Activity Filters

​
--cmd
string
Shell command patternSupports patterns:
  • contains - default
  • ^prefix - starts with
  • $suffix - ends with
  • =exact - exact match
  • *glob - glob pattern
hcom listen --cmd "git push"
hcom listen --cmd "^npm"
​
--file
string
File write/edit eventsSupports glob patterns:
hcom listen --file "*.py"
hcom listen --file "src/auth.py"
​
--collision
boolean
File edit collisions (two agents edit same file within 30s)
hcom listen --collision

​
Lifecycle Filters

​
--action
enum
Lifecycle action: created, started, ready, stopped, batch_launched
hcom listen --action stopped --agent luna

​
Time Filters

​
--after
string
Events after timestamp (ISO-8601)
hcom listen --after 2026-01-01T12:00:00Z
​
--before
string
Events before timestamp (ISO-8601)
hcom listen --before 2026-01-01T12:00:00Z

​
Custom SQL

​
--sql
string
Raw SQL WHERE clause against events_v viewCombined with filter flags using AND logic.
hcom listen --sql "type='status' AND status_val='blocked'"

​
Shortcuts

​
--idle
string
Wait for agent to go idle (listening status)Equivalent to: --agent NAME --status listening
hcom listen --idle luna --timeout 300
​
--blocked
string
Wait for agent to be blocked (needs approval)Equivalent to: --agent NAME --status blocked
hcom listen --blocked nova

​
Examples

​
Basic Message Waiting

# Wait for any message
hcom listen

# Quick check (0.1s poll)
hcom listen 1

# Wait 5 minutes
hcom listen 300

​
Workflow Coordination

# Wait for agent to finish and go idle
hcom listen --idle luna --timeout 600
if [ $? -eq 0 ]; then
  echo "Luna is idle, sending next task"
  hcom send @luna -- Next task: run tests
fi

# Wait for agent to stop
hcom listen --sql "stopped:luna" --timeout 300

​
Message Monitoring

# Wait for request from luna
hcom listen --from luna --intent request

# Wait for mention in thread
hcom listen --mention @nova --thread pr-99

# Wait for broadcast message
hcom listen --type message --sql "json_extract(data, '$.scope') = 'broadcast'"

​
Activity Monitoring

# Wait for file edit
hcom listen --file "src/auth.py" --timeout 300

# Wait for any Python file edit
hcom listen --file "*.py"

# Wait for git command
hcom listen --cmd "git" --agent luna

# Wait for collision
hcom listen --collision

​
Status Changes

# Wait for agent to be blocked (needs approval)
hcom listen --blocked nova --timeout 120

# Wait for tool completion
hcom listen --agent luna --context "tool:Bash" --timeout 60

# Wait for agent startup
hcom listen --action ready --agent nova

​
JSON Output for Scripts

# Parse message in script
MSG=$(hcom listen --json --timeout 30)
if [ $? -eq 0 ]; then
  FROM=$(echo "$MSG" | jq -r '.from')
  TEXT=$(echo "$MSG" | jq -r '.text')
  echo "Message from $FROM: $TEXT"
fi

​
Filter Combinations

# Multiple filter flags (AND logic)
hcom listen --agent luna --type status --context "tool:*"

# Flags + SQL
hcom listen --agent nova --sql "json_extract(data, '$.detail') LIKE '%error%'"

# Wait for specific file edit by specific agent
hcom listen --agent luna --file "config.json"

​
Exit Codes

  • 0 - Message/event received
  • 1 - Timeout or error
  • 130 - Interrupted (SIGTERM)

​
Behavior

​
Message Delivery

  • Sets agent status to listening during wait
  • Advances read cursor when messages arrive
  • Returns immediately if unread messages exist
  • Wakes instantly on new messages (TCP notify + relay)

​
Heartbeat

Updates last_stop timestamp periodically so stale cleanup doesn’t disconnect the agent.

​
Lookback Window

Filter mode checks last 10 seconds for recent matches before waiting.

​
Status Updates

  • listening → active when message received
  • adhoc tools: marked inactive on timeout

​
Remote Sync

With relay enabled:
  • Long-polls MQTT for remote events (25s)
  • Short TCP select for local notifications (1s)
Local-only:
  • TCP select wakes on notification (30s)
  • No TCP: frequent polling (100ms)

​
Notes

  • Requires hcom start for identity
  • Filter mode uses temporary subscription (auto-cleanup)
  • Multiple filter flags combine with AND logic
  • Supports events_v SQL view (computed columns)
  • Quick timeout ≤1s becomes 0.1s poll mode
  • SIGTERM triggers clean shutdown with exit code 130

Build docs developers (and LLMs) love

Get started for freeTalk to us