Back to Details

hcom-agent-messaging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

hcom — multi-agent communication for AI coding tools

hcom — 面向 AI 编程工具的多 Agent 通信

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.
If the user wants a quick operating pattern from the current session, one headed hub with mostly headless workers, or practical thread and handoff defaults, use the separate 
using-hcom
skill instead of this one.
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              # TUI dashboard
运行在不同终端中的 AI Agent 彼此隔离。hcom 通过 hooks 和共享数据库将它们连接起来，使它们能够实时地互相发送消息、观察并 spawn 彼此。
如果用户希望快速获取当前会话的操作模式、使用一个 headed hub 搭配大多数 headless workers，或了解实用的 thread 和 handoff 默认设置，请改用单独的 
using-hcom
skill。
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              # 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
告诉任意 Agent：
向 claude 发送消息
当 codex 空闲时，给它发送下一个任务
监听 gemini 的文件编辑，逐一审查并发送反馈（如果发现 bug）
fork 你自己，以调查该 bug 并汇报结果
找出哪个 Agent 处理过 terminal_id 对应的代码，恢复它并询问它为什么写得一塌糊涂

what agents can do

Agent 可以做什么

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.
Message：实时地互相发送消息，为 handoff 汇总上下文。
Observe：观察彼此的 transcripts、文件编辑、终端屏幕和命令历史。
Subscribe：订阅彼此；在状态变化、文件编辑或特定事件发生时收到通知，并自动作出反应。
Spawn、Fork、Resume、Kill：在任何 terminal emulator 中互相执行这些操作。
运行 
hcom --help
查看完整的命令语法和 flags。

tool support

工具支持

tooldeliveryconnect
claude code (incl. subagents)automatic
hcom claude
gemini cli (>= 0.26.0)automatic
hcom gemini
codexautomatic
hcom codex
opencodeautomatic
hcom opencode
any other ai toolmanual 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.
工具消息投递连接方式
claude code（包括 subagents）自动
hcom claude
gemini cli（>= 0.26.0）自动
hcom gemini
codex自动
hcom codex
opencode自动
hcom opencode
任何其他 AI 工具通过 
hcom listen
手动
hcom start
（在工具内运行）
对于所有通过 hcom 启动的工具，session binding（hcom transcript、按 session id 执行的 hcom r/f）会在首次收到消息或首次收到提示时完成。

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 outputmeaningaction
command not foundnot installedinstall 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 installedready
[✗] claude
tool not foundinstall the AI tool first
如果用户调用此 skill 时未提供参数：
  1. 运行 
    hcom status
    — 如果显示“command not found”，请先安装：
bash
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
  1. 运行 
    hcom hooks add
    ，为所有检测到的工具安装 hooks
  2. 重启 AI 工具以激活 hooks
状态输出含义操作
command not found未安装通过 
brew install aannoo/hcom/hcom
、上述 curl 安装脚本或 
pip install hcom
安装
[~] claude
工具存在，但未安装 hooks执行 
hcom hooks add
，然后重启
[✓] claude
已安装 hooks已就绪
[✗] claude
找不到该工具请先安装 AI 工具

troubleshooting

故障排查

"hcom not working"

“hcom 无法工作”

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
bash
hcom status          # check installation
hcom hooks status    # check hooks specifically
hcom relay status    # check cross-device relay
缺少 hooks？执行 
hcom hooks add
，然后重启工具。
仍然有问题？
bash
hcom reset all && hcom hooks add

close all ai tool windows

close all ai tool windows

hcom claude # fresh start
undefined
hcom claude # fresh start
undefined

"messages not arriving"

“消息未送达”

symptomdiagnosisfix
agent not in 
hcom list
agent stopped or never boundrelaunch or wait for binding
message sent but not deliveredcheck 
hcom events --last 5
verify @mention matches agent name/tag
wrong agent receives message@mention ambiguityuse 
@tag-
prefix for reliable routing
messages leaking between workflowsno thread isolationalways use 
--thread
症状诊断修复
Agent 不在 
hcom list
中		Agent 已停止或从未绑定重新启动，或等待绑定完成
消息已发送但未送达检查 
hcom events --last 5
确认 @mention 与 Agent 名称/tag 完全匹配
错误的 Agent 收到了消息@mention 存在歧义使用 
@tag-
前缀以确保可靠路由
消息在不同工作流之间泄漏没有 thread 隔离始终使用 
--thread

intent system

intent 系统

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
Agent 会遵循其 bootstrap 中的以下规则：
  • --intent request
    -> Agent 始终响应
  • --intent inform
    -> Agent 仅在有帮助时响应
  • --intent ack
    -> Agent 不响应

thread mechanics

thread 机制

  • a thread is a conversation namespace, not a fixed membership group
  • @mentions on each individual message determine that message's delivery — the seed does not lock membership
  • hcom send --thread X
    as broadcast (no @mentions) reuses the last-seed member list, but this is unreliable for hub routing
  • the sender is never included in 
    delivered_to
     — if a hub creates a thread by sending 
    @eng- @review-
    , the hub is NOT a thread member
  • to make the hub a thread member, include 
    @<hub-name>
    (the hub's CVCV name from the hcom system context) in the @mentions of the seed message
  • for important replies and final outcomes, workers should also 
    @<hub-name>
    explicitly — do not rely on broadcast routing to reach the hub
  • the hub discovers its CVCV name from the hcom system context (
    Your name: <name>
    ) or via 
    hcom list
  • thread 是一个 conversation namespace，而不是固定的成员组
  • 每条单独消息中的 @mentions 决定该消息的投递对象；seed 不会锁定成员资格
  • 将 
    hcom send --thread X
    作为 broadcast（不带 @mentions）发送时，会复用最近一次 seed 的成员列表，但这种方式对 hub routing 不可靠
  • 发送者绝不包含在 
    delivered_to
    中    ——如果 hub 通过发送 
    @eng- @review-
    创建 thread，hub 并不是该 thread 的成员
  • 要让 hub 成为 thread 成员，请在 seed 消息的 @mentions 中包含 
    @<hub-name>
    （hub 在 hcom system context 中的 CVCV name）
  • 对于重要回复和最终结果，worker 也应明确 
    @<hub-name>
    ——不要依赖 broadcast routing 将结果送达 hub
  • hub 可从 hcom system context（
    Your name: <name>
    ）或 
    hcom list
    中发现自己的 CVCV name

sandbox / permission issues

沙箱 / 权限问题

bash
export HCOM_DIR="$PWD/.hcom"     # project-local mode
hcom hooks add                   # installs to project dir
bash
export HCOM_DIR="$PWD/.hcom"     # project-local mode
hcom hooks add                   # installs to project dir
设置 
HCOM_DIR
后，将改用该路径，而不是 
~/.hcom
。

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.
将脚本放在 
~/.hcom/scripts/
中，扩展名为 
.sh
或 
.py
。使用 
hcom run <name> "task"
运行。有关完整的注释模板，请参阅 
references/script-template.md
；也可以在 Agent 内运行 
hcom run docs --scripts
。

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/kill — without it, scripts hang on confirmation prompt
  • 绝不要使用 
    sleep
    ——改用 
    hcom events --wait
    或 
    hcom listen
  • 绝不要硬编码 Agent 名称——从启动输出中的 
    grep '^Names: '
    解析
  • 始终使用 
    --thread
    ——否则消息会在不同工作流之间泄漏
  • 始终使用 
    trap cleanup ERR INT TERM
    ——否则孤立的 headless Agent 会无限期运行
  • 清理时始终使用 
    hcom kill
    （不要使用 
    stop
    ）    ——
    hcom kill
    还会关闭 terminal pane
  • 始终转发 
    --name
    ——hcom 会注入该参数，脚本必须继续传递它
  • 启动或终止时始终使用 
    --go
    ——否则脚本会卡在确认提示上

agent topologies

Agent 拓扑结构

topologyagentspattern
worker-reviewer2worker sends result, reviewer reads transcript, sends APPROVED/FIX
pipelineN sequentialeach stage reads previous via 
hcom transcript
, signals via thread
ensembleN+1 (judge)N agents answer independently, judge reads all via 
hcom events --sql
hub-spoke1+Ncoordinator broadcasts to 
@tag-
, workers report back
reactiveN
hcom events sub
triggers agent actions on file edits/status changes
拓扑Agent 数量模式
worker-reviewer2worker 发送结果，reviewer 读取 transcript，并发送 APPROVED/FIX
pipelineN 个，按顺序执行每个阶段通过 
hcom transcript
读取上一阶段的信息，并通过 thread 发出信号
ensembleN+1（judge）N 个 Agent 独立作答，judge 通过 
hcom events --sql
读取全部结果
hub-spoke1+Ncoordinator 向 
@tag-
广播，worker 回报结果
reactiveN
hcom events sub
在文件编辑或状态变化时触发 Agent 操作

files

文件

whatlocation
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
.
内容位置
数据库
~/.hcom/hcom.db
配置
~/.hcom/config.toml
日志
~/.hcom/.tmp/logs/
用户脚本
~/.hcom/scripts/
设置 
HCOM_DIR
后，将改用该路径，而不是 
~/.hcom
。

reference files

参考文件

filewhen 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 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
文件何时阅读
references/patterns.md
编写多 Agent 脚本——6 种经过测试的模式，包含完整代码和真实事件 JSON
references/cross-tool.md
claude + codex + gemini + opencode 的协作细节及各工具的疑难问题
references/gotchas.md
调试脚本——时序、消息投递、intent 系统和清理问题
references/script-template.md
从头编写新脚本——带注释的完整模板
references/scripts/
6 个经过测试且可正常运行的示例脚本

more info

更多信息

bash
hcom --help              # all commands
hcom <command> --help    # command details
github: https://github.com/aannoo/hcom
bash
hcom --help              # all commands
hcom <command> --help    # command details
github: https://github.com/aannoo/hcom