aannoo/hcom-workflow-scripts

hcom workflow scripts

build custom multi-agent workflow scripts that launch, coordinate, and manage AI coding agents via hcom.

decision tree

1. write a new script → use the script template below + read references/script-template.md
2. choose a multi-agent pattern → read references/patterns.md
3. need hcom architecture details → read references/architecture.md
4. cross-tool scripting (claude + codex) → read references/cross-tool-scripting.md
5. debug a script → read references/debugging.md
6. want pre-built scripts → check references/scripts/ directory

script template

every hcom workflow script follows this structure:

#!/usr/bin/env bash
# description shown in `hcom run` listing.
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 workflow logic ---

# launch agent
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 ' ')

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

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

place scripts in ~/.hcom/scripts/ as .sh or .py. run with hcom run <name> "task".

agent topologies

| topology | agents | hcom primitives | |----------|--------|-----------------| | 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 |

communication primitives

| what | how | latency | |------|-----|---------| | send message | hcom send @name --thread T --intent X -- "msg" | under 1s (claude), 1-3s (codex) | | wait for signal | hcom events --wait N --sql "..." | under 1s after match | | read agent's work | hcom transcript @name --full --detailed | under 1s | | react to file changes | hcom events sub --file "*.py" | under 2s | | react to agent idle | hcom events sub --idle name | under 2s | | cross-device | hcom send @name:DEVICE -- "msg" | 1-5s | | structured handoff | hcom send --title X --transcript N-M:full --files a.py | under 1s |

required flags for script launches

| flag | why it's required | |------|-------------------| | --go | skips confirmation prompt — without it, script hangs forever | | --headless | runs agent as detached background process | | --tag X | groups agents for @X- routing (essential for scripts) | | --hcom-prompt "..." | sets the agent's initial task |

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 — 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
• wait for codex before messaging — hcom events --wait 30 --idle "$codex_name"

timing reference (measured)

| operation | claude | codex | |-----------|--------|-------| | launch to ready | 3-5s | 5-10s | | message delivery | under 1s | 1-3s | | transcript read | under 1s | under 1s | | full 2-agent round-trip | 15-25s | 25-40s | | full 4-agent ensemble | 25-35s | n/a |

integration with external systems

hcom scripts are bash — they can call any CLI tool:

# ci/cd trigger
hcom send @worker- --from "github-actions" -- "PR merged, deploy"

# webhook notification
curl -X POST $WEBHOOK -d "$(hcom events --sql "msg_thread='${thread}'" --last 5)"

# pipe output
echo "complex task description" | hcom send @worker-

reference files

| file | when to read | |------|-------------| | references/script-template.md | writing a new script from scratch — full template with commentary | | references/patterns.md | choosing and implementing multi-agent patterns — 6 tested examples | | references/architecture.md | understanding hcom internals — db schema, hooks, delivery pipeline, events | | references/cross-tool-scripting.md | claude + codex mixed scripts — per-tool quirks, timing, session binding | | references/debugging.md | fixing broken scripts — common failures, stale agents, message delivery | | references/scripts/basic-messaging.sh | tested: two agents exchange messages | | references/scripts/review-loop.sh | tested: worker-reviewer feedback loop | | references/scripts/cross-tool-duo.sh | tested: claude architect + codex engineer | | references/scripts/ensemble-consensus.sh | tested: 3 independent agents + judge | | references/scripts/cascade-pipeline.sh | tested: sequential plan then execute pipeline | | references/scripts/codex-worker.sh | tested: codex codes, claude reviews transcript |