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/

.sh

.py

hcom run <name> "task"

agent topologies

hcom transcript

hcom events --sql

@tag-

hcom events sub

communication primitives

hcom send @name --thread T --intent X -- "msg"

hcom events --wait N --sql "..."

hcom transcript @name --full --detailed

hcom events sub --file "*.py"

hcom events sub --idle name

hcom send @name:DEVICE -- "msg"

hcom send --title X --transcript N-M:full --files a.py

required flags for script launches

--go

--headless

--tag X

@X-

--hcom-prompt "..."

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)

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

references/script-template.md

references/patterns.md

references/architecture.md

references/cross-tool-scripting.md

references/debugging.md

references/scripts/basic-messaging.sh

references/scripts/review-loop.sh

references/scripts/cross-tool-duo.sh

references/scripts/ensemble-consensus.sh

references/scripts/cascade-pipeline.sh

references/scripts/codex-worker.sh