hcom
Hook your coding agents together
hcom is a CLI that coding agents use to message, watch, and spawn each other across terminals.
Works with Claude Code, Codex, OpenCode, Kilo Code, Pi, Oh My Pi, Antigravity, Cursor, Kimi and Copilot - in any combination, without changing how you use them.
Use it to coordinate pipelines, run different AI CLIs as each other's subagents, or just instead of copy-paste.
Single Rust binary, no background services. Start an agent with hcom in front, then prompt normally.
https://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43
Install
brew install aannoo/hcom/hcom
Other install options
# With Python
uv tool install hcom # or: pip install hcom
# macOS, Linux, Android (Termux), and WSL
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
# Windows (native, PowerShell)
irm https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.ps1 | iex
# Update any existing install to latest hcom version
hcom update
Quickstart
Terminal 1:
hcom claude # codex / opencode / kilo / pi / omp / agy / cursor-agent / kimi / copilot / gemini
Terminal 2:
hcom codex
Prompt:
ask the other agent their favorite cakereview what claude did and send it fixesspawn 3x opencode, split work, collect resultsfork yourself to investigate the bug and report backwhen codex goes idle, send it the next task
Open the TUI dashboard:
hcom
What agents can do
Message each other in real time: requests, updates, replies, threads, and bundled 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 or headless.
How it works
Hooks record activity to a local SQLite database and deliver messages from it.
agent → hooks → db → hooks → other agent
Messages arrive mid-turn (injected between tool calls) or wake idle agents immediately.
Each agent has a name. You and other agents can inspect its:
- status and inbox
- live terminal screen
- transcript
- event log, including file edits and tool calls
Agents can subscribe to events and react instantly. 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.
Any other AI tool without hooks can join by running hcom start. Any process can wake agents with hcom send.
Terminal
Every agent runs in a real terminal you can see, scroll, and interrupt. Any emulator works for spawning. kitty, wezterm, tmux, zellij, waveterm, cmux, herdr also support closing panes from hcom kill.
To configure a custom terminal open/close setup, tell an 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 --allto disconnect all devices. - Use a private/custom/self-hosted broker with
--brokerand--passwordfor 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
- Forward secrecy. A leaked PSK can decrypt old captured traffic.
- Per-device attribution inside a relay. Sender identity is routing metadata, not authorization. Every enrolled device speaks with full authority.
- Prompt injection from an authenticated peer. Enrollment is total trust — a peer can launch, kill, and drive agents via RPC, not just send messages. Only enroll devices you would give shell access to.
- Local OS compromise. hcom trusts the local user account and
~/.hcom/config.toml. It does not defend against another user on the same account or malware with filesystem access.
Storage
The PSK is stored in ~/.hcom/config.toml. On Unix, hcom writes that file with mode 0600.
hcom keeps the PSK out of environment variables. Remote config_get and config_set refuse relay_psk, relay_token, relay_id, and the broker URL. hcom relay status shows only a short fingerprint so two devices can verify they share the same key without printing it.
Anyone who can read that file — another user on the same OS account, malware, or a backup written without preserving permissions — has the full PSK.
Incident response
Run hcom relay off --all. It asks every reachable trusted peer to disable the relay, then disables it locally, so your agents stop acting on attacker messages. It is best-effort damage control, not containment: the attacker's device ignores the request.
The PSK cannot be revoked. There is no server to notify and no denylist to update. Anyone who has the PSK can keep using the old relay until you stop using it.
To keep using relay after a leak, create a new relay with hcom relay new and move every trusted device to the new token. Rotation also changes the relay_id, so retained state on the old broker topics is orphaned.
Troubleshoot
hcom status # diagnostics
hcom reset all # clear and archive: database + hooks + config
Uninstall
hcom hooks remove # safely remove all hcom hooks
brew uninstall hcom # or: rm $(which hcom)
Reference
Tools
Supported tools
| Tool | Message delivery | Connect |
|---|---|---|
| Claude Code | automatic | hcom claude |
| Gemini CLI | automatic | hcom gemini |
| Codex CLI | automatic | hcom codex |
| Antigravity CLI | automatic | hcom agy |
| OpenCode | automatic | hcom opencode |
| Kilo Code | automatic | hcom kilo |
| Pi | automatic | hcom pi |
| Oh My Pi | automatic | hcom omp |
| Cursor CLI | automatic | hcom cursor-agent |
| Kimi | automatic | hcom kimi |
| Copilot CLI | automatic | hcom copilot |
| Anything else | manual via hcom listen |
hcom start (run inside tool) |
hcom r <session_id> # Resume a session started outside hcom
hcom f <session_id> # Fork a session in hcom
Claude Code headless and subagents
Detached background processes in print mode stay alive. Manage through the TUI.
hcom claude -p 'say hi in hcom' # print mode (separate Agent SDK credits)
hcom claude --headless # Run normal claude in background pty (works for any tool)
For subagents, run hcom claude, then