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://raw.githubusercontent.com/aannoo/hcom/main/install.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

---

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

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://raw.githubusercontent.com/aannoo/hcom/main/install.sh | sh
   

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

---

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"

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)"
# your logic here

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

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

---

reference files

---

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