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

hcom send @name -- "msg"

hcom transcript @name --full

--detailed

hcom term inject name "text" --enter

hcom events --sql "..." --last N

hcom events sub --idle name

hcom 1 claude --tag X --go --headless

hcom send --title X --transcript 1-20:full --files a.py

hcom send @name:DEVICE -- "msg"

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

--headless

--tag X

--hcom-prompt

--hcom-system-prompt

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

hcom start

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

pip install hcom

[~] claude

hcom hooks add

[✓] claude

[✗] claude

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

still broken?

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

"messages not arriving"

hcom list

hcom events --last 5

@tag-

--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)"
# 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

~/.hcom/hcom.db

~/.hcom/config.toml

~/.hcom/.tmp/logs/

~/.hcom/scripts/

with

HCOM_DIR

~/.hcom

reference files

references/patterns.md

references/cli-reference.md

references/cross-tool.md

references/gotchas.md

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