hcom-agent-messaging

name	hcom-agent-messaging
description	| Use when this capability is needed.

hcom — multi-agent communication for AI coding tools

AI agents running in separate terminals are isolated. hcom connects them via hooks and a shared database so they can message, watch, and spawn each other in real-time.

curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
hcom claude       # or: hcom gemini, hcom codex, hcom opencode
hcom              # TUI dashboard

---

what humans can do

tell any agent:

send a message to claude

when codex goes idle send it the next task

watch gemini's file edits, review each and send feedback if any bugs

fork yourself to investigate the bug and report back

find which agent worked on terminal_id code, resume them and ask why it sucks

---

what agents can do

capability	command	tested behavior
message each other	hcom send @name -- "msg"	delivers in under 1s (claude), 1-3s (codex)
read each other's transcripts	hcom transcript @name --full	includes tool I/O with --detailed
view/inject into terminal screens	hcom term inject name "text" --enter	approves prompts, types commands
query event history	hcom events --sql "..." --last N	file edits, commands, status, lifecycle
subscribe to activity	hcom events sub --idle name	real-time notifications via system messages
spawn/fork/resume/kill agents	hcom 1 claude --tag X --go --headless	headless background agents for scripts
build context bundles	hcom send --title X --transcript 1-20:full --files a.py	structured handoffs between agents
collision detection	automatic	2 agents edit same file within 30s, both notified
cross-device messaging	hcom send @name:DEVICE -- "msg"	via MQTT relay, 1-5s latency

---

essential commands (quick reference)

launch agents

hcom 1 claude --tag worker --go --headless --hcom-prompt "your task"
hcom 1 codex --tag engineer --go --headless --hcom-prompt "your task"
hcom 3 claude --tag team --go --headless    # batch launch

flags: --go (skip confirmation), --headless (background), --tag X (group routing), --hcom-prompt (initial task), --hcom-system-prompt (role/personality)

send messages

hcom send @luna -- "direct message"
hcom send @worker- -- "all agents tagged worker"
hcom send @luna @nova -- "multiple targets"
hcom send -- "broadcast to everyone"
hcom send @luna --intent request -- "expecting reply"
hcom send @luna --intent inform -- "fyi, no reply needed"
hcom send @luna --thread review-1 -- "threaded conversation"

wait for events (replaces sleep in scripts)

hcom events --wait 120 --sql "msg_text LIKE '%DONE%'"
hcom events --wait 60 --idle luna
hcom listen 30    # block until any message

read other agents' work

hcom transcript @luna --full              # complete conversation
hcom transcript @luna --full --detailed   # with tool I/O, file edits
hcom transcript @luna --last 3            # last 3 exchanges

agent lifecycle

hcom list                # show all active agents
hcom kill luna --go      # kill + close terminal pane
hcom kill all --go       # kill everything
hcom stop luna --go      # graceful stop (preserves session)
hcom r luna              # resume stopped agent
hcom f luna --tag rev    # fork (clone session, new identity)

event subscriptions (reactive)

hcom events sub --idle luna              # notify when luna goes idle
hcom events sub --file "*.py" --once     # one-shot: next .py file edit
hcom events sub --collision              # file edit collisions

---

tool support

tool	hooks	delivery	session binding	launch to ready
claude code (incl. subagents)	10 hooks	automatic (hook output)	instant on sessionstart	3-5s
gemini cli (>= 0.26.0)	7 hooks	automatic (hook output)	instant on beforeagent	3-5s
codex	1 hook (notify)	PTY injection	on first agent-turn-complete	5-10s
opencode	4 handlers (plugin)	plugin TCP endpoint	on plugin binding	3-5s
any ai tool	manual	hcom start inside tool	on first command	varies

codex note: session binding takes 5-10s. always wait before sending messages:

hcom events --wait 30 --idle "$codex_name"

---

setup

if the user invokes this skill without arguments:

1. run hcom status — if "command not found", install first:

   curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
   

2. run hcom hooks add to install hooks for all detected tools
3. restart the AI tool for hooks to activate

status output	meaning	action
command not found	not installed	install via curl or pip install hcom
[~] claude	tool exists, hooks not installed	hcom hooks add then restart
[✓] claude	hooks installed	ready
[✗] claude	tool not found	install the AI tool first

---

troubleshooting

"hcom not working"

hcom status          # check installation
hcom hooks status    # check hooks specifically
hcom relay status    # check cross-device relay

hooks missing? hcom hooks add then restart tool.

still broken?

hcom reset all && hcom hooks add
# close all ai tool windows
hcom claude          # fresh start

"messages not arriving"

symptom	diagnosis	fix
agent not in hcom list	agent stopped or never bound	relaunch or wait for binding
message sent but not delivered	check hcom events --last 5	verify @mention matches agent name/tag
codex agent shows inactive	stale_cleanup (session didn't bind in 30s)	wait for idle before sending
wrong agent receives message	@mention ambiguity	use @tag- prefix for reliable routing
messages leaking between workflows	no thread isolation	always use --thread

intent system

agents follow these rules from their bootstrap:

• --intent request → agent always responds
• --intent inform → agent responds only if useful
• --intent ack → agent does not respond

sandbox / permission issues

export HCOM_DIR="$PWD/.hcom"     # project-local mode
hcom hooks add                   # installs to project dir

---

scripting patterns (tested with real agents)

basic two-agent messaging

thread="t-$(date +%s)"
launch_out=$(hcom 1 claude --tag worker --go --headless \
  --hcom-prompt "count 1-5. send result: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"RESULT: <answer>\". stop: hcom stop" 2>&1)
worker=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')

launch_out=$(hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "wait for @worker-. send DONE to bigboss. stop: hcom stop" 2>&1)

hcom events --wait 120 --sql "msg_thread='${thread}' AND msg_text LIKE '%DONE%'"
hcom kill all --go

worker-reviewer feedback loop

# worker does task, reviewer evaluates, sends APPROVED or FIX feedback
# worker corrects if needed, loop until approved
# see references/patterns.md for full tested scripts

cross-tool: claude designs, codex implements

# claude sends spec to @eng- (codex), codex implements, claude approves
# CRITICAL: wait for codex binding before messaging
hcom events --wait 30 --idle "$codex_name"
# see references/patterns.md for full tested scripts

ensemble: 3 agents + judge

# 3 agents independently answer, judge aggregates via hcom events --sql
# agents run in parallel (same wall-clock as 1 agent)
# see references/patterns.md for full tested scripts

---

script template (for workflow scripts in ~/.hcom/scripts/)

#!/usr/bin/env bash
set -euo pipefail

LAUNCHED_NAMES=()
track_launch() {
  local names=$(echo "$1" | grep '^Names: ' | sed 's/^Names: //')
  for n in $names; do LAUNCHED_NAMES+=("$n"); done
}
cleanup() {
  for name in "${LAUNCHED_NAMES[@]}"; do
    hcom kill "$name" --go 2>/dev/null || true
  done
}
trap cleanup ERR

name_flag=""
task=""
while [[ $# -gt 0 ]]; do
  case "$1" in --name) name_flag="$2"; shift 2 ;; -*) shift ;; *) task="$1"; shift ;; esac
done
name_arg=""
[[ -n "$name_flag" ]] && name_arg="--name $name_flag"

thread="workflow-$(date +%s)"

key rules:

• always parse and forward --name (hcom injects it)
• always use --go on launch/kill
• always use --headless for script agents
• always use --thread for message isolation
• use hcom events --wait instead of sleep
• capture agent names from grep '^Names: ' in launch output
• cleanup with trap cleanup ERR + hcom kill

---

files

what	location
database	~/.hcom/hcom.db
config	~/.hcom/config.toml
logs	~/.hcom/.tmp/logs/
user scripts	~/.hcom/scripts/

with HCOM_DIR set, uses that path instead of ~/.hcom.

---

reference files

file	when to read
references/patterns.md	writing multi-agent scripts — 6 tested patterns with full code and real event JSON
references/cli-reference.md	complete command reference with all flags and examples
references/cross-tool.md	claude + codex + gemini + opencode collaboration details and per-tool quirks
references/gotchas.md	debugging scripts — timing, stale agents, codex binding, message delivery issues

---

more info

hcom --help              # all commands
hcom <command> --help    # command details
hcom run docs            # full CLI + config + API reference

github: https://github.com/aannoo/hcom

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.