// Multi-agent communication for AI coding tools. Agents message, watch, and spawn each other across terminals. Use when setting up hcom, troubleshooting delivery, or writing multi-agent scripts.
| name | hcom-agent-messaging |
| description | Multi-agent communication for AI coding tools. Agents message, watch, and spawn each other across terminals. Use when setting up hcom, troubleshooting delivery, or writing multi-agent scripts. |
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
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
Message each other in real-time, bundle context for handoffs.
Observe each other: transcripts, file edits, terminal screens, command history.
Subscribe to each other: notify on status changes, file edits, specific events. React automatically.
Spawn, fork, resume, kill each other, in any terminal emulator.
run hcom --help for full command syntax and flags.
| tool | delivery | connect |
|---|---|---|
| claude code (incl. subagents) | automatic | hcom claude |
| gemini cli (>= 0.26.0) | automatic | hcom gemini |
| codex | automatic | hcom codex |
| opencode | automatic | hcom opencode |
| any other ai tool | manual via hcom listen | hcom start (run inside tool) |
session binding (hcom transcript, hcom r/f by session id) happens on first message or first prompt for all hcom-launched tools.
if the user invokes this skill without arguments:
hcom status — if "command not found", install first:
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
hcom hooks add to install hooks for all detected tools| status output | meaning | action |
|---|---|---|
| command not found | not installed | install via brew install aannoo/hcom/hcom, the curl installer above, 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 |
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
| 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 |
| wrong agent receives message | @mention ambiguity | use @tag- prefix for reliable routing |
| messages leaking between workflows | no thread isolation | always use --thread |
agents follow these rules from their bootstrap:
--intent request -> agent always responds--intent inform -> agent responds only if useful--intent ack -> agent does not respondexport HCOM_DIR="$PWD/.hcom" # project-local mode
hcom hooks add # installs to project dir
place scripts in ~/.hcom/scripts/ as .sh or .py. run with hcom run <name> "task". see references/script-template.md for the full annotated template, or run hcom run docs --scripts inside an agent.
sleep — use hcom events --wait or hcom listengrep '^Names: ' in launch output--thread — without it, messages leak across workflowstrap cleanup ERR INT TERM — orphan headless agents run indefinitelyhcom kill for cleanup (not stop) — kill also closes the terminal pane--name — hcom injects it, scripts must propagate it--go on launch/kill — without it, scripts hang on confirmation prompt| topology | agents | pattern |
|---|---|---|
| worker-reviewer | 2 | worker sends result, reviewer reads transcript, sends APPROVED/FIX |
| pipeline | N sequential | each stage reads previous via hcom transcript, signals via thread |
| ensemble | N+1 (judge) | N agents answer independently, judge reads all via hcom events --sql |
| hub-spoke | 1+N | coordinator broadcasts to @tag-, workers report back |
| reactive | N | hcom events sub triggers agent actions on file edits/status changes |
| 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.
| file | when to read |
|---|---|
references/patterns.md | writing multi-agent scripts — 6 tested patterns with full code and real event JSON |
references/cross-tool.md | claude + codex + gemini + opencode collaboration details and per-tool quirks |
references/gotchas.md | debugging scripts — timing, message delivery, intent system, cleanup |
references/script-template.md | writing a new script from scratch — full template with commentary |
references/scripts/ | 6 tested, working example scripts |
hcom --help # all commands
hcom <command> --help # command details
github: https://github.com/aannoo/hcom