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.
If the user wants a quick operating pattern from the current session, one headed hub with mostly headless workers, or practical thread and handoff defaults, use the separate
skill instead of this one.
bash
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
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
for full command syntax and flags.
tool support
| tool | delivery | connect |
|---|
| claude code (incl. subagents) | automatic | |
| gemini cli (>= 0.26.0) | automatic | |
| codex | automatic | |
| opencode | automatic | |
| any other ai tool | manual via | (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.
setup
if the user invokes this skill without arguments:
- run — if "command not found", install first:
bash
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
- run to install hooks for all detected tools
- restart the AI tool for hooks to activate
| status output | meaning | action |
|---|
| command not found | not installed | install via brew install aannoo/hcom/hcom
|
| tool exists, hooks not installed | then restart |
| hooks installed | ready |
| tool not found | install the AI tool first |
troubleshooting
"hcom not working"
bash
hcom status # check installation
hcom hooks status # check hooks specifically
hcom relay status # check cross-device relay
hooks missing?
then restart tool.
still broken?
bash
hcom reset all && hcom hooks add
# close all ai tool windows
hcom claude # fresh start
"messages not arriving"
| symptom | diagnosis | fix |
|---|
| agent not in | agent stopped or never bound | relaunch or wait for binding |
| message sent but not delivered | check | verify @mention matches agent name/tag |
| wrong agent receives message | @mention ambiguity | use prefix for reliable routing |
| messages leaking between workflows | no thread isolation | always use |
intent system
agents follow these rules from their bootstrap:
- -> agent always responds
- -> agent responds only if useful
- -> agent does not respond
thread mechanics
- a thread is a conversation namespace, not a fixed membership group
- @mentions on each individual message determine that message's delivery — the seed does not lock membership
- as broadcast (no @mentions) reuses the last-seed member list, but this is unreliable for hub routing
- the sender is never included in — if a hub creates a thread by sending , the hub is NOT a thread member
- to make the hub a thread member, include (the hub's CVCV name from the hcom system context) in the @mentions of the seed message
- for important replies and final outcomes, workers should also explicitly — do not rely on broadcast routing to reach the hub
- the hub discovers its CVCV name from the hcom system context () or via
sandbox / permission issues
bash
export HCOM_DIR="$PWD/.hcom" # project-local mode
hcom hooks add # installs to project dir
workflow scripting
place scripts in
as
or
. run with
. see
references/script-template.md
for the full annotated template, or run
inside an agent.
key rules
- never use — use or
- never hardcode agent names — parse from in launch output
- always use — without it, messages leak across workflows
- always use
trap cleanup ERR INT TERM
- always use for cleanup (not ) — kill also closes the terminal pane
- always forward — hcom injects it, scripts must propagate it
- always use on launch/kill — without it, scripts hang on confirmation prompt
agent topologies
| topology | agents | pattern |
|---|
| worker-reviewer | 2 | worker sends result, reviewer reads transcript, sends APPROVED/FIX |
| pipeline | N sequential | each stage reads previous via , signals via thread |
| ensemble | N+1 (judge) | N agents answer independently, judge reads all via |
| hub-spoke | 1+N | coordinator broadcasts to , workers report back |
| reactive | N | triggers agent actions on file edits/status changes |
files
| what | location |
|---|
| database | |
| config | |
| logs | |
| user scripts | |
with
set, uses that path instead of
.
reference files
| file | when to read |
|---|
| writing multi-agent scripts — 6 tested patterns with full code and real event JSON |
| claude + codex + gemini + opencode collaboration details and per-tool quirks |
| debugging scripts — timing, message delivery, intent system, cleanup |
references/script-template.md
| writing a new script from scratch — full template with commentary |
| 6 tested, working example scripts |
more info
bash
hcom --help # all commands
hcom <command> --help # command details