Claude Skill

hcom-agent-messaging

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.

LLM Mart · 0 points · 0 views 1 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download aannoo-hcom-skills_hcom-agent-messaging-962cbef.zip · 19 KB
aannoo/hcom 530 84 forks MIT Updated 11h ago

Install

skills CLI npx skills add https://github.com/aannoo/hcom/tree/main/skills/hcom-agent-messaging
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install aannoo-hcom@llmmart
Git git clone https://github.com/aannoo/hcom.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole aannoo/hcom collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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 kilo, hcom pi, hcom omp, hcom agy, hcom cursor-agent, hcom kimi, hcom copilot, hcom grok
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 hcom --help for full command syntax and flags.

tool support

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
kilo code automatic hcom kilo
antigravity automatic hcom agy
cursor automatic hcom cursor-agent
copilot automatic hcom copilot
grok build automatic hcom grok
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.

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 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

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
message reaches more than one agent duplicate base name across tags target the full @tag-name to hit exactly one
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

workflow scripting

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.

key rules

  • never use sleep — use hcom events --wait or hcom listen
  • never hardcode agent names — parse from grep '^Names: ' in launch output
  • always use --thread — without it, messages leak across workflows
  • always use trap cleanup ERR INT TERM — orphan headless agents run indefinitely
  • always use hcom kill for cleanup (not stop) — kill also closes the terminal pane
  • always forward --name — hcom injects it, scripts must propagate it
  • always use --go on launch commands — without it, scripts hang on confirmation prompt (hcom kill never prompts, so --go is optional there)

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 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

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/cross-tool.md claude + codex + gemini + opencode + kilo + pi + omp + antigravity + cursor + kimi + copilot + grok 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

more info

hcom --help              # all commands
hcom <command> --help    # command details

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

Files (hcom)
  • references
    • scripts
      • basic-messaging.sh 1.8 KB 
        #!/usr/bin/env bash
# Two agents exchange messages: worker sends result, reviewer acknowledges.
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
}

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"
task="${task:-count from 1 to 5}"
thread="basic-$(date +%s)"

trap cleanup ERR INT TERM

launch_out=$(hcom 1 claude --tag worker --go --headless \
  --hcom-prompt "Do this: ${task}. Send result to @reviewer- via: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"RESULT: <your answer>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
worker=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Worker: $worker"

launch_out=$(hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "Wait for a message from @worker-. When received, reply: hcom send \"@${worker}\" --thread ${thread} --intent ack -- \"ACK: received\". Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"DONE\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
reviewer=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Reviewer: $reviewer"
echo "Thread: $thread"
echo "Waiting..."

hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%DONE%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
      • cascade-pipeline.sh 2.1 KB 
        #!/usr/bin/env bash
# Sequential pipeline: planner designs, executor reads planner's transcript and implements.
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
}

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"
task="${task:-list 5 prime numbers}"
thread="casc-$(date +%s)"

trap cleanup ERR INT TERM

# Stage 1: Planner
launch_out=$(hcom 1 claude --tag plan --go --headless \
  --hcom-prompt "Plan how to: ${task}. Write 2 sentences. Send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"PLAN DONE: <plan>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
planner=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Planner: $planner"

echo "Waiting for plan..."
hcom events --wait 60 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%PLAN DONE%'" $name_arg >/dev/null 2>&1 || { echo "FAIL (planner timeout)"; exit 1; }

# Stage 2: Executor reads planner's transcript
launch_out=$(hcom 1 claude --tag exec --go --headless \
  --hcom-prompt "Read planner's work: hcom transcript @${planner} --last 3. Execute the plan for: ${task}. Send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"EXEC DONE: <result>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
executor=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Executor: $executor"

echo "Waiting for execution..."
hcom events --wait 60 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%EXEC DONE%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
      • codex-worker.sh 1.8 KB 
        #!/usr/bin/env bash
# Codex writes code, Claude reviews Codex's transcript. Cross-tool review pattern.
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
}

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"
task="${task:-write /tmp/hello.py that prints hello world and run it}"
thread="codex-$(date +%s)"

trap cleanup ERR INT TERM

launch_out=$(hcom 1 codex --tag coder --go --headless \
  --hcom-prompt "Do this: ${task}. When done, send output: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"CODE DONE: <output>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
coder=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Coder (Codex): $coder"

launch_out=$(hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "Wait for @coder- CODE DONE message. Read their transcript: hcom transcript @${coder} --last 5 --full. Send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"REVIEWED: <pass/fail>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
reviewer=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Reviewer (Claude): $reviewer"
echo "Thread: $thread"
echo "Waiting..."

hcom events --wait 180 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%REVIEWED%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
      • cross-tool-duo.sh 1.9 KB 
        #!/usr/bin/env bash
# Claude designs spec, Codex implements it. Cross-tool collaboration.
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
}

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"
task="${task:-write a python function that adds two numbers}"
thread="duo-$(date +%s)"

trap cleanup ERR INT TERM

# Launch Codex engineer
launch_out=$(hcom 1 codex --tag eng --go --headless \
  --hcom-prompt "Wait for spec from @arch-. Implement it. Then confirm: hcom send \"@arch-\" --thread ${thread} --intent inform -- \"IMPLEMENTED\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
eng=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Engineer (Codex): $eng"

# Launch Claude architect
launch_out=$(hcom 1 claude --tag arch --go --headless \
  --hcom-prompt "Design a 2-3 sentence spec for: ${task}. Send to @eng-: hcom send \"@eng-\" --thread ${thread} --intent request -- \"SPEC: <spec>\". Wait for confirmation. Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"APPROVED\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
arch=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Architect (Claude): $arch"
echo "Thread: $thread"
echo "Waiting..."

hcom events --wait 180 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%APPROVED%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
      • ensemble-consensus.sh 1.8 KB 
        #!/usr/bin/env bash
# 3 agents independently answer same question, judge picks best.
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
}

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"
task="${task:-what is 17 * 23}"
thread="ens-$(date +%s)"

trap cleanup ERR INT TERM

for i in 1 2 3; do
  launch_out=$(hcom 1 claude --tag "c${i}" --go --headless \
    --hcom-prompt "Answer: ${task}. Send ONLY your answer: hcom send \"@judge-\" --thread ${thread} --intent inform -- \"C${i}: <answer>\". Then stop: hcom stop" 2>&1)
  track_launch "$launch_out"
  name=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
  echo "Contestant $i: $name"
done

launch_out=$(hcom 1 claude --tag judge --go --headless \
  --hcom-prompt "Wait for 3 answers in thread '${thread}'. Check: hcom events --sql \"msg_thread='${thread}'\" --last 10. Pick best. Send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"VERDICT: <winner>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
judge=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Judge: $judge"
echo "Thread: $thread"
echo "Waiting..."

hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%VERDICT%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
      • review-loop.sh 2 KB 
        #!/usr/bin/env bash
# Worker does task, reviewer reads transcript and gives feedback. Loop until approved.
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
}

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"
task="${task:-count from 1 to 10 in Turkish}"
thread="review-$(date +%s)"

trap cleanup ERR INT TERM

launch_out=$(hcom 1 claude --tag worker --go --headless \
  --hcom-prompt "Task: ${task}. Do it, then send: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"ROUND 1 DONE: <result>\". If you get feedback, fix and resend as ROUND 2 DONE. After APPROVED, send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"FINAL\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
worker=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Worker: $worker"

launch_out=$(hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "You review @worker- output. On ROUND N DONE message, check the result. If correct: hcom send \"@${worker}\" --thread ${thread} --intent inform -- \"APPROVED\". If wrong: hcom send \"@${worker}\" --thread ${thread} --intent request -- \"FIX: <issue>\". Then stop: hcom stop" 2>&1)
track_launch "$launch_out"
reviewer=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "Reviewer: $reviewer"
echo "Thread: $thread"
echo "Waiting..."

hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%FINAL%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
hcom events --sql "msg_thread='${thread}'" --last 10 2>&1
    • cross-tool.md 6.9 KB 
      # Cross-Tool Patterns: Claude + Codex + Gemini + OpenCode + Kilo Code + Pi + OMP + Antigravity + Cursor + Kimi + Copilot + Grok

Verified behavior when mixing different AI coding tools via hcom.

## Typical combos

- **worker + reviewer across tools** — one tool implements, another reviews. Catches blind spots from training-data overlap.
- **sandboxed executor** — Codex runs tests or touches risky files; Claude or Gemini orchestrates from outside the sandbox.
- **diverse answers, one judge** — fan out the same question to multiple tools, one agent reads all transcripts and picks.

## Per-Tool Technical Details

### Claude Code
- **Hooks**: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PermissionRequest, SubagentStart, SubagentStop, Notification, SessionEnd
- **Payload**: JSON via stdin
- **Exit codes**: 0=allow, 2=block with message delivery
- **Session binding**: On SessionStart hook, immediate
- **Message delivery**: Hook output in `additionalContext`
- **Headless mode**: `-p` (print) flag for background, `setsid()` detach
- **Subagent support**: Yes, via Task with background=true
- **Bootstrap injection**: On SessionStart, includes command reference, active agents, scripts

### Codex
- **Hooks**: SessionStart, UserPromptSubmit, PreToolUse (Bash), PostToolUse (Bash), Stop
- **Payload**: JSON via stdin
- **Session binding**: On SessionStart hook, immediate (same as Claude)
- **Message delivery**: Hook-based auto-delivery when hcom-launched; PTY injection fallback for vanilla sessions
- **Sandbox modes**: `workspace` (--sandbox workspace-write + network), `danger-full-access` (--dangerously-bypass-approvals-and-sandbox), `none` (raw)
- **Bootstrap injection**: Via `-c developer_instructions=<bootstrap>` at launch time
- **Transcript path**: Derived from thread ID, searched via glob in `$CODEX_HOME/sessions/`

### Gemini CLI
- **Hooks**: sessionstart, beforeagent, afteragent, beforetool, aftertool, notification, sessionend
- **Payload**: JSON via stdin
- **Session binding**: On beforeagent hook
- **Message delivery**: Hook output
- **System prompt**: Written to `~/.hcom/system-prompts/gemini.md`, set via `GEMINI_SYSTEM_MD` env var
- **Policy auto-approval**: `~/.gemini/policies/hcom.toml`
- **Transcript path**: Derived from session_id, searched in `~/.gemini/chats/`

### OpenCode
- **Hooks**: start, status, read, stop — via TypeScript plugin
- **Plugin location**: `$XDG_CONFIG_HOME/opencode/plugins/hcom.ts`
- **Session binding**: Via TCP binding ceremony (plugin calls `hcom opencode-start --session-id`)
- **Message delivery**: Plugin TCP endpoint
- **Auto-approval**: `OPENCODE_PERMISSION` env var scoped to safe hcom command prefixes

### Kilo Code

- **Delivery**: Shares OpenCode's `hcom.ts` plugin and `opencode-*` hook handlers.
- **Plugin location**: `$XDG_CONFIG_HOME/kilo/plugins/hcom.ts`
- **Session binding**: Via the OpenCode-family TCP binding ceremony.
- **Transcript**: SQLite at `$XDG_DATA_HOME/kilo/kilo.db` unless `KILO_DB` overrides it.
- **Resume/Fork**: `--session <id>` / `--session <id> --fork`
- **Message delivery**: Plugin TCP endpoint
- **Auto-approval**: `KILO_PERMISSION` env var scoped to safe hcom command prefixes

### Cursor (cursor-agent)
- **Hooks**: sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, stop, sessionEnd
- **Payload**: JSON via stdin
- **Session binding**: On sessionStart hook, immediate
- **Message delivery**: Hook-based when hcom-launched. Active turn → body in postToolUse `additional_context`. Idle agent → a sentinel turn whose `stop` hook carries the body in `followup_message` (one extra turn vs. other tools — the idle wake costs a round-trip).
- **Background mode**: HeadlessPty — runs under a PTY even when headless (cursor-agent `--print` drops the beforeSubmitPrompt + stop hooks, so hcom keeps the interactive TUI). No detached `--print` background like Claude.
- **Approval handling**: cursor's interactive approval prompt ("Run this command?") is detected by PTY screen scrape; a message held at an approval surfaces status `blocked: approval pending`.
- **Status detail**: edit tool is `StrReplace` (not `Edit`); file/edit tools key the path off `path` (not `file_path`); shell has the `run_terminal_cmd` variant; delegates are `Task`/`Subagent`.
- **Fork**: not supported (cursor-agent has no native branch primitive — only `--resume`/`--continue`); resume preserved.
- **Transcript**: cursor-agent writes JSONL under `~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl`. Parser support is limited: no timestamps, `cwd`, or tool-result blocks; user prompts require wrapper removal.

### Grok Build
- **Hooks**: none. hcom installs nothing for Grok; binding, status and delivery all come over the ACP client on hcom's private leader.
- **Session binding**: from the leader's session roster (every resident session on the private leader is the TUI's). A session that newly opens idle (`/new`, `/resume` from disk) is bound at once; switching to an already-open session (dashboard, `/resume`) emits nothing, so hcom follows it when a user prompt starts there.
- **Status**: from the bound session's broadcasts: queue (turn start), `tool_call`, a permission/question request (`session/request_permission` etc., sent only when a human must answer; approvals Grok decides itself never show as blocked), `turn_completed` (stop reason; anything but end_turn/cancelled is `failure:<reason>`).
- **Bootstrap**: `--rules` at launch.
- **Message delivery**: `hcom grok` runs the TUI on a private leader socket; a second client (`grok agent --leader stdio`) queues each batch as a normal prompt (`sendNow:false`). Nothing is typed into the composer, drafts are untouched, and a busy agent runs the batch after its current work. The batch is acked when Grok starts running it; one dropped before it ran (removed from the queue, transport lost) stays unread and is queued again.
- **Session id**: a new `hcom grok` gets `--session-id <uuid>`. Without it the TUI sits on its welcome screen over a hidden session and never draws turns queued there.
- **Permissions**: the TUI answers them. With `hcom config auto_approve 1`, hcom's ACP client answers "allow once" first for a single safe `hcom …` shell command (no chaining, redirection or substitution); nothing is written to Grok's config.
- **Rejected flags**: `-p`/`--single`/`--prompt-file`/`--prompt-json` (one-shot), leader flags (hcom owns the leader), and `--allow`/`--deny`/`--disable-web-search` (Grok ignores them in leader mode; put rules in Grok's config). `--no-subagents` is passed as `GROK_SUBAGENTS=0`.
- **Resume/fork**: `--resume` / `--fork-session`; worktree flags are not replayed. `hcom r <session-id>` finds sessions under `$GROK_HOME/sessions`.
- **Transcript**: `$GROK_HOME/sessions/<url-encoded cwd>/<id>/updates.jsonl`.

## Working Patterns

See `scripts/cross-tool-duo.sh` for Claude architect + Codex engineer, and `scripts/codex-worker.sh` for Codex coder + Claude reviewer. See `patterns.md` for all 6 tested patterns including Claude + Gemini mixed perspectives.
    • gotchas.md 6.3 KB 
      # hcom Script Gotchas

Common issues and fixes discovered during real testing.

## Script Hangs Forever

**Cause:** Missing `--go` flag on launch commands such as `hcom 1 claude`.

**Fix:** Include `--go` on launch commands in scripts. `hcom kill` does not
prompt, so `--go` is optional for kill commands.

```bash
# WRONG - hangs waiting for user confirmation
hcom 1 claude --tag worker --headless --hcom-prompt "..."

# RIGHT
hcom 1 claude --tag worker --go --headless --hcom-prompt "..."
```

## Agent Not Receiving Messages

**Diagnosis steps:**
```bash
hcom list                    # Is agent alive? What status?
hcom events --last 5         # Was message actually sent?
hcom events --agent luna     # What has luna seen recently?
```

**Common causes and fixes:**

| Cause | How to detect | Fix |
|-------|---------------|-----|
| Agent already stopped | `hcom list` shows inactive/missing | Check timing; agent may finish before message arrives |
| Agent has not bound session yet | `hcom list` shows "launching" | Wait: `hcom events --wait 30 --idle "$name"` |
| Mistyped @-mention | `send` fails: "non-existent or stopped agents" + Available list | Names resolve exactly — use the exact agent name or `@tag-` group, no partial/prefix matching |
| No matching thread | Agent sees no messages | Both sides must use exact same `--thread` value |
| Message scope mismatch | Event `scope` is "mentions" but agent not in `mentions` array | Verify @mention matches agent name or tag |
| Identity binding failed | Agent not in `instances` table | Check `HCOM_PROCESS_ID` env var propagation |

## Messages Leaking Between Workflows

**Cause:** No `--thread` isolation. Without threads, all messages in a broadcast scope reach all agents.

**Fix:** Every workflow must use a unique thread ID:
```bash
thread="my-workflow-$(date +%s)"
# All messages in this workflow use --thread
hcom send @worker- --thread "$thread" -- "task"
hcom events --wait 120 --sql "msg_thread='${thread}' AND msg_text LIKE '%DONE%'"
```

**Why timestamps work:** `$(date +%s)` gives epoch seconds. Even if two workflows start in the same second, different thread prefixes (e.g., "review-" vs "ensemble-") prevent collision.

## SQL LIKE Matching Behavior

`msg_text LIKE '%APPROVED%'` also matches `"approved": true` in JSON because SQLite LIKE is case-insensitive for ASCII characters. This is actually convenient for most use cases.

**Precision matching when needed:**
```bash
# Case-sensitive match (use GLOB instead of LIKE)
hcom events --sql "msg_text GLOB '*APPROVED*'"

# Match exact word boundary
hcom events --sql "msg_text LIKE '% APPROVED%' OR msg_text LIKE 'APPROVED%'"
```

## hcom events --wait Exit Code

Returns **0** on match, **1** on timeout, **2** on SQL error. Use exit code directly:

```bash
hcom events --wait 60 --sql "msg_thread='${thread}' AND msg_text LIKE '%DONE%'" $name_arg >/dev/null 2>&1
case $? in
  0) echo "MATCHED" ;;
  1) echo "TIMEOUT" ;;
  2) echo "SQL ERROR — check your query" ;;
esac
```

In scripts where you only care about success vs failure, `&& echo PASS || echo FAIL` is fine — exit codes 1 and 2 are both failures.

## Agent Name Capture

Names are random 4-letter CVCV words (luna, nemo, bali, kiwi, cora, etc.). Never hardcode them. Always parse from launch output:

```bash
launch_out=$(hcom 1 claude --tag worker --go --headless --hcom-prompt "..." 2>&1)
track_launch "$launch_out"
name=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
# $name is now "luna" or "nemo" etc.
echo "Launched: $name"
```

**For batch launches (multiple agents):**
```bash
launch_out=$(hcom 3 claude --tag team --go --headless --hcom-prompt "..." 2>&1)
# Names: luna nemo bali (space-separated)
names=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //')
for n in $names; do
  LAUNCHED_NAMES+=("$n")
  echo "Launched: $n"
done
```

## Agent Cleanup on Error

Without cleanup, orphan headless agents run indefinitely consuming resources. Always use `trap cleanup ERR INT TERM` and track launched names. See `script-template.md` for the full pattern.

**Use `hcom kill` not `hcom stop`:** Kill sends SIGTERM and closes the terminal pane. Stop preserves the session for resume but leaves the pane open.

## Broadcast vs Mention Routing

**Broadcast (no @mentions):**
```bash
hcom send -- "everyone sees this"  # No @ prefix = broadcast
```

**Mention (targeted):**
```bash
hcom send @luna -- "only luna sees this"         # Direct mention
hcom send @worker- -- "all workers see this"     # Tag prefix
hcom send @luna @nova -- "luna and nova see this" # Multiple mentions
```

**Common mistake:** Forgetting `--` before the message text. Without `--`, the message text might be parsed as flags.

## Heartbeat and Stale Detection

Agents are marked stale (inactive) if their heartbeat is not updated within tool-dependent thresholds. After system sleep/wake, hcom gives a grace period where heartbeat checks are suspended to prevent mass stale detection after laptop lid close/open.

## Intent System Misuse

**Wrong:** Not using intents, causing agents to over-respond:
```bash
hcom send @worker- -- "FYI: I updated the config"  # No intent = ambiguous
```

**Right:**
```bash
hcom send @worker- --intent inform -- "FYI: I updated the config"   # Worker won't respond
hcom send @worker- --intent request -- "Review this code"           # Worker must respond
hcom send @worker- --intent ack -- "Got it, thanks"                 # Worker ignores
```

The bootstrap teaches agents: `request -> always respond`, `inform -> respond only if useful`, `ack -> don't respond`.

## Thread vs Reply-To vs Scope

| Mechanism | When to use | What it does |
|-----------|-------------|-------------|
| `--thread` | Group related messages | Creates namespace for conversation isolation |
| `--reply-to <id>` | Reference specific message | Links message to an event ID |
| `@mentions` | Target specific agents | Controls delivery scope |
| Broadcast (no @) | Everyone needs to see | Delivers to all active/listening agents |

## TTY/PTY Issues

**Agent shows as "blocked" in hcom list:**
- Cause: Approval prompt detected (OSC9 sequence) or output unstable
- Fix: Agent needs user to approve a tool call, or the PTY delivery detected instability

**Agent terminal pane does not close on kill:**
- Cause: Terminal preset close command failed or pane ID was not captured
- Fix: Manually close the terminal tab/pane. Check `hcom config terminal` for preset.
    • patterns.md 6 KB 
      # Tested Multi-Agent Patterns

Every pattern below has been tested with real agents. Event outputs are from real runs. Full working scripts are in `references/scripts/`.

---

## Pattern 1: Basic Two-Agent Messaging

Worker sends result, reviewer acknowledges, DONE signal to orchestrator.

**Script:** `scripts/basic-messaging.sh`

Key logic:

```bash
# Worker does task, sends result to reviewer
hcom 1 claude --tag worker --go --headless \
  --hcom-prompt "Do: ${task}. Send result: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"RESULT: <answer>\". Then: hcom stop"

# Reviewer acks worker, sends DONE to orchestrator
hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "Wait for @worker-. Reply ACK. Send DONE to @bigboss. Then: hcom stop"

# Orchestrator waits for DONE
hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%DONE%'"
```

**Real event JSON from test run:**
```json
{"id":42,"type":"message","instance":"mila","data":{"from":"mila","text":"RESULT: 1, 2, 3","scope":"mentions","mentions":["niro"],"intent":"inform","thread":"basic-1774354927","sender_kind":"instance","delivered_to":["niro"]}}
{"id":45,"type":"message","instance":"niro","data":{"from":"niro","text":"DONE","scope":"broadcast","intent":"inform","thread":"basic-1774354927","sender_kind":"instance","delivered_to":["mila"]}}
```

---

## Pattern 2: Worker-Reviewer Feedback Loop

Worker does task, reviewer evaluates, sends APPROVED or FIX feedback, worker corrects if needed.

**Script:** `scripts/review-loop.sh`

Key logic:

```bash
# Worker: does task, sends ROUND N DONE, listens for FIX/APPROVED
--hcom-prompt "Task: ${task}. Send ROUND 1 DONE to @reviewer-. If FIX feedback, fix and resend as ROUND 2 DONE. After APPROVED, send FINAL to @bigboss."

# Reviewer: checks each round, sends APPROVED or FIX
--hcom-prompt "On ROUND N DONE: if correct send APPROVED, if wrong send FIX: <issue>."

# Orchestrator waits for FINAL (after APPROVED)
hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%FINAL%'"
```

**Key insight:** The FIX/APPROVED protocol creates a natural feedback loop. Workers self-correct based on reviewer feedback. Multiple rounds happen automatically.

---

## Pattern 3: Ensemble Consensus (N Agents + Judge)

N agents independently answer the same question, judge reads all answers and aggregates.

**Script:** `scripts/ensemble-consensus.sh`

Key logic:

```bash
# Launch N contestants in a loop
for i in 1 2 3; do
  hcom 1 claude --tag "c${i}" --go --headless \
    --hcom-prompt "Answer independently: ${task}. Send ONLY your answer: hcom send \"@judge-\" --thread ${thread} --intent inform -- \"C${i}: <answer>\". Then: hcom stop."
done

# Judge reads all answers via event query
--hcom-prompt "Wait for 3 answers. Check: hcom events --sql \"msg_thread='${thread}' AND msg_text LIKE 'C%'\" --last 10. Synthesize. Send VERDICT."

# Orchestrator waits for VERDICT
hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%VERDICT%'"
```

**Key insight:** The judge uses `hcom events --sql` to query thread messages, reading all answers in one call. Agents run in parallel so N agents cost same wall-clock as 1.

---

## Pattern 4: Sequential Cascade Pipeline

Each stage reads previous stage's transcript for full context handoff.

**Script:** `scripts/cascade-pipeline.sh`

Key logic:

```bash
# Stage 1: Planner
hcom 1 claude --tag plan --go --headless \
  --hcom-prompt "Plan: ${task}. Send PLAN DONE."

# Wait for plan, then launch stage 2 with transcript reference
hcom events --wait 60 --sql "msg_thread='${thread}' AND msg_text LIKE '%PLAN DONE%'"

# Stage 2: Executor reads planner's transcript
hcom 1 claude --tag exec --go --headless \
  --hcom-prompt "Read planner transcript: hcom transcript @${planner} --last 3. Execute the plan. Send EXEC DONE."
```

**Key insight:** `hcom transcript @name --full` is the context handoff mechanism. Each pipeline stage gets the complete work product of the previous stage. Use `--detailed` to include tool I/O (Bash output, file edits).

---

## Pattern 5: Cross-Tool (Claude + Codex)

Claude designs the spec, Codex implements in sandbox.

**Script:** `scripts/cross-tool-duo.sh`

Key logic:

```bash
# Codex waits for spec, implements
hcom 1 codex --tag eng --go --headless \
  --hcom-prompt "Wait for spec from @arch-. Implement it. Send IMPLEMENTED."

# Claude designs spec, sends to Codex, waits for confirmation
hcom 1 claude --tag arch --go --headless \
  --hcom-prompt "Design spec: ${task}. Send SPEC to @eng-. Wait for IMPLEMENTED. Send APPROVED."

# Orchestrator waits for APPROVED
hcom events --wait 180 --sql "msg_thread='${thread}' AND msg_text LIKE '%APPROVED%'"
```

---

## Pattern 6: Codex Codes, Claude Reviews Transcript

Codex writes and runs code, Claude reads Codex's full transcript to review.

**Script:** `scripts/codex-worker.sh`

Key logic:

```bash
# Codex does the work
hcom 1 codex --tag coder --go --headless \
  --hcom-prompt "Do: ${task}. Send CODE DONE to @reviewer-."

# Claude reviews by reading Codex's transcript
hcom 1 claude --tag reviewer --go --headless \
  --hcom-prompt "Wait for CODE DONE. Read transcript: hcom transcript @${coder} --last 5 --full. Send REVIEWED: pass/fail."
```

**Key insight:** Claude reads Codex's complete transcript (including Bash output, file writes, command results) via `hcom transcript @name --full --detailed`. This enables deep code review without sharing files.

---

## Summary Table

| # | Pattern | Agents | Tools | Use case |
|---|---------|--------|-------|----------|
| 1 | Basic messaging | 2 | Claude x2 | Simple task delegation |
| 2 | Review loop | 2 | Claude x2 | Self-correcting feedback |
| 3 | Ensemble consensus | 4 | Claude x4 | Diverse perspectives, best answer |
| 4 | Cascade pipeline | 2 | Claude x2 | Sequential plan-then-execute |
| 5 | Cross-tool duo | 2 | Claude+Codex | Design + sandbox implementation |
| 6 | Codex->Claude review | 2 | Codex+Claude | Code execution + transcript review |
    • script-template.md 4.7 KB 
      # hcom script template — annotated reference

complete annotated template for writing hcom workflow scripts.

## file location and discovery

scripts live in `~/.hcom/scripts/` as `.sh` or `.py` files. hcom discovers them automatically:

```bash
cp my-script.sh ~/.hcom/scripts/my-script.sh
chmod +x ~/.hcom/scripts/my-script.sh
hcom run my-script "task description"
```

description: line 2 comment (after shebang) is shown in `hcom run` listing.

user scripts shadow bundled scripts (confess, debate, fatcow, onidle) with the same name.

## full template with commentary

```bash
#!/usr/bin/env bash
# brief description shown in hcom run list.
set -euo pipefail

# --- agent tracking ---
# every script must track launched agents for cleanup.
# without this, orphan headless agents run indefinitely.
LAUNCHED_NAMES=()
track_launch() {
  # hcom launch prints "Names: luna" or "Names: luna nemo kira"
  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
    # use kill (not stop) — kill also closes the terminal pane
    hcom kill "$name" --go 2>/dev/null || true
  done
}
# trap ensures cleanup runs on any error or signal
trap cleanup ERR INT TERM

# --- identity propagation ---
# hcom injects --name before script args. MUST parse and forward it.
# without this, the script's hcom commands can't identify the caller.
name_flag=""
task=""
while [[ $# -gt 0 ]]; do
  case "$1" in
    --name) name_flag="$2"; shift 2 ;;
    -h|--help) echo "Usage: hcom run my-script [OPTIONS] TASK"; exit 0 ;;
    -*) shift ;;  # skip unknown flags
    *) task="$1"; shift ;;
  esac
done
name_arg=""
[[ -n "$name_flag" ]] && name_arg="--name $name_flag"
# default task if none provided
task="${task:-default task here}"

# --- unique thread for isolation ---
# without --thread, messages leak across concurrent workflows
thread="my-workflow-$(date +%s)"

# --- launch agents ---
launch_out=$(hcom 1 claude --tag worker --go --headless \
  --hcom-prompt "task: ${task}. when done: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"DONE: <result>\". then: hcom stop" 2>&1)
track_launch "$launch_out"
worker=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
echo "worker: $worker"

# --- wait for completion signal ---
# use hcom events --wait, NEVER sleep
hcom events --wait 120 \
  --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%DONE%'" \
  $name_arg >/dev/null 2>&1 && echo "PASS" || echo "TIMEOUT"

# --- cleanup ---
trap - ERR
for name in "${LAUNCHED_NAMES[@]}"; do
  hcom kill "$name" --go 2>/dev/null || true
done
```

## key conventions

| convention | why |
|------------|-----|
| `--go` on every launch/kill | prevents script from hanging on confirmation prompt |
| `--headless` on every launch | runs agent in background (no terminal window needed) |
| `--tag X` on every launch | enables `@X-` group routing (message every agent in the group at once) |
| `--thread` on every send/wait | isolates messages per workflow run |
| `--intent` on every send | tells recipient whether to respond |
| `trap cleanup ERR INT TERM` | ensures orphan agents are killed on script failure or signal |
| parse `--name` from args | hcom injects this — must forward to all hcom commands |
| capture name from `Names:` | agent names are random 4-letter words, never hardcode |

## python scripts

```python
#!/usr/bin/env python3
"""brief description shown in hcom run list."""
import subprocess, sys, time, json

def hcom(*args):
    result = subprocess.run(["hcom"] + list(args), capture_output=True, text=True)
    return result.stdout.strip()

def main():
    thread = f"py-{int(time.time())}"
    # launch agent
    out = hcom("1", "claude", "--tag", "worker", "--go", "--headless",
               "--hcom-prompt", f"do task. send DONE to @bigboss via thread {thread}. stop.")
    # parse name
    for line in out.split("\n"):
        if line.startswith("Names: "):
            name = line.replace("Names: ", "").strip()
            break
    # wait
    hcom("events", "--wait", "120", "--sql",
         f"type='message' AND msg_thread='{thread}' AND msg_text LIKE '%DONE%'")
    # cleanup
    hcom("kill", name, "--go")

if __name__ == "__main__":
    main()
```

## batch launches

```bash
# launch 3 agents at once
launch_out=$(hcom 3 claude --tag team --go --headless \
  --hcom-prompt "answer the question" 2>&1)
# "Names: luna nemo kira" (space-separated)
names=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //')
for n in $names; do
  LAUNCHED_NAMES+=("$n")
done

# with batch coordination
launch_out=$(hcom 3 claude --tag team --go --headless \
  --batch-id "batch-$(date +%s)" \
  --hcom-prompt "answer the question" 2>&1)
```
  • SKILL.md 6.5 KB 
    ---
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.
---

# 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.

```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 kilo, hcom pi, hcom omp, hcom agy, hcom cursor-agent, hcom kimi, hcom copilot, hcom grok
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 `hcom --help` for full command syntax and flags.

---

## tool support

| 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` |
| kilo code | automatic | `hcom kilo` |
| antigravity | automatic | `hcom agy` |
| cursor | automatic | `hcom cursor-agent` |
| copilot | automatic | `hcom copilot` |
| grok build | automatic | `hcom grok` |
| 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.

---

## setup

if the user invokes this skill without arguments:

1. run `hcom status` — if "command not found", install first:
   ```bash
   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 `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 |

---

## troubleshooting

### "hcom not working"

```bash
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?
```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 `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 |
| message reaches more than one agent | duplicate base name across tags | target the full `@tag-name` to hit exactly one |
| 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

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

---

## workflow scripting

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.

### key rules

- **never use `sleep`** — use `hcom events --wait` or `hcom listen`
- **never hardcode agent names** — parse from `grep '^Names: '` in launch output
- **always use `--thread`** — without it, messages leak across workflows
- **always use `trap cleanup ERR INT TERM`** — orphan headless agents run indefinitely
- **always use `hcom kill` for cleanup** (not `stop`) — kill also closes the terminal pane
- **always forward `--name`** — hcom injects it, scripts must propagate it
- **always use `--go`** on launch commands — without it, scripts hang on confirmation prompt (`hcom kill` never prompts, so `--go` is optional there)

### 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 `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 |

---

## 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/cross-tool.md` | claude + codex + gemini + opencode + kilo + pi + omp + antigravity + cursor + kimi + copilot + grok 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 |

---

## more info

```bash
hcom --help              # all commands
hcom <command> --help    # command details
```

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

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude