Agent skill

hcom-workflow-scripts

Build multi-agent workflow scripts using hcom. Use this skill when the user wants to create custom hcom scripts, design multi-agent pipelines, write automation that coordinates Claude and Codex agents, or build applications that use hcom as the communication backbone. Covers script patterns, agent topologies, hcom internals, and tested examples.

Stars 187
Forks 23

Install this agent skill to your Project

npx add-skill https://github.com/aannoo/hcom/tree/main/skills/hcom-workflow-scripts

SKILL.md

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:

bash
#!/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 messaginghcom 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:

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

Expand your agent's capabilities with these related and highly-rated skills.

aannoo/hcom

hcom-agent-messaging

Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode. Use this skill when the human user needs help, status, or reference about hcom - when user asks questions like "how to setup hcom", "hcom not working", "explain hcom", or any hcom troubleshooting.

187 23
Explore
davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298
Explore
davila7/claude-code-templates

openrlhf-training

High-performance RLHF framework with Ray+vLLM acceleration. Use for PPO, GRPO, RLOO, DPO training of large models (7B-70B+). Built on Ray, vLLM, ZeRO-3. 2× faster than DeepSpeedChat with distributed architecture and GPU resource sharing.

23,776 2,298
Explore
davila7/claude-code-templates

gguf-quantization

GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements.

23,776 2,298
Explore
davila7/claude-code-templates

Claude Code Guide

Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent.

23,776 2,298
Explore
davila7/claude-code-templates

qdrant-vector-search

High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.

23,776 2,298
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results