hcom
Hook your coding agents together
Prefix agents with hcom to let them message, watch, and spawn each other across terminals.
https://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43
Install
brew install aannoo/hcom/hcom
Other install options
# Shell installer for macOS, Linux, Android (Termux), and WSL
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
# With PyPI
uv tool install hcom # or: pip install hcom
Quickstart
Terminal 1:
hcom claude # codex / gemini / opencode
Terminal 2:
hcom codex
Prompt:
ask the other agent their favorite cakereview what claude did and send it fixesspawn 3x gemini, split work, collect resultsfork yourself to investigate the bug and report back
Open the TUI:
hcom
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.
How it works
Hooks record activity to a local SQLite database and deliver messages from it.
agent → hooks → db → hooks → other agent
For Claude Code, Gemini CLI, Codex, and OpenCode, messages arrive mid-turn (injected between tool calls) or wake idle agents immediately. Any other AI tool can join by running hcom start. Any process can wake agents with hcom send.
Collision detection is on by default: if two agents edit the same file within 30 seconds, both get notified.
Hooks go into config dirs under ~/ (or HCOM_DIR) on first run. If you aren't using hcom, the hooks do nothing.
Terminal
Every agent runs in a real terminal you can see, scroll, and interrupt. Any emulator works for spawning; kitty, wezterm, and tmux additionally support closing panes from hcom kill.
To configure a custom terminal open/close setup, tell agent to run:
hcom config terminal --info
Cross-device
Connect agents across machines via MQTT relay.
hcom relay new # get token
hcom relay connect <token> # on each device
hcom relay status # check connection
hcom relay off|on # toggle
Relay Security
Security
- Relay payloads are end-to-end encrypted. Brokers do not see data.
- Treat the join token like an SSH key or API key.
- If the token may have leaked, run
hcom relay off --all to disconnect all devices.
- Use a private/custom/self-hosted broker with
--broker and --password for better security.
Security model
hcom relay is one trust domain for one operator's devices. Membership is all-or-nothing. There are no scoped roles, read-only peers, or per-device permissions.
Relay payloads use a shared PSK with XChaCha20-Poly1305. The encryption binds each payload to the relay, topic, and timestamp. A replay guard drops duplicate envelopes inside a freshness window.
Brokers and network observers cannot read or forge payloads without the PSK. They can still see metadata: topic names, timing, message sizes, and connection patterns.
What the token means
The join token contains the relay ID, broker URL, and raw PSK. hcom does not ask a server to validate it. It has no expiry, no scope, and no revocation list.
On public brokers, a leaked token gives an attacker full control of the relay. They can decrypt captured traffic, publish authenticated relay traffic, send text to listening agents, launch agents on enrolled devices, kill running agents, and use remote relay RPCs. If those agents can run tools, treat that as shell access on every enrolled device in the relay.
On private brokers with --password, the token still leaks the PSK, so captured traffic is still exposed. But the token alone is not enough to publish unless the attacker also has the broker password. Use a private broker when broker-side access control matters, or when the metadata shape of your traffic is itself sensitive. --password is broker access control, not another layer of message encryption.
Limits by design