`hcom`

Hook your coding agents together

CLI tool that agents use to message, watch, and spawn each other across terminals.

Start an agent with hcom in front, then prompt normally.

Use it to coordinate multi-agent pipelines, run different AI CLIs as each other's subagents, or just to avoid copy-pasting.

Works with: claude, codex, opencode, copilot, qoder, grok, hermes, pi, omp, agy, cursor, kimi, kilo, gemini

https://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43

Install

python - macOS, Linux, Windows:

uv tool install hcom

homebrew - macOS, Linux:

brew install aannoo/hcom/hcom

Other install options

# macOS, Linux, Android
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh

# Windows
irm https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.ps1 | iex

# Update any existing install
hcom update

Quickstart

Terminal 1:

hcom claude

Terminal 2:

hcom codex

Prompt:

ask the other agent their favorite cake

review what claude did and send it fixes
spawn 3x opencode, split work, collect results
fork yourself to investigate the bug and report back
when codex goes idle, send it the next task

Open the TUI dashboard:

hcom

What agents can do

Message each other in real time: mid-turn or wake immediately when idle
Observe each other: status, transcripts, file edits, live terminal screens, command history.
Subscribe and notify on status changes, file edits, collisions, specific events. React automatically.
Spawn, fork, resume, kill 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

Hooks activate only when an agent is launched with hcom in front. Normal usage is unaffected.

Any other AI tool without hooks can join by running hcom start

In any CLI tool, prompt:

> run this command: `hcom start`

Keep it listening for messages:

> stay connected to hcom

Any process can wake agents with hcom send

Send messages from any process/script:

hcom send -b @luna -- "wake up and do this task"

Chain with hcom events:

hcom events --idle luna --wait 600 && hcom send -b @nova -- "luna is done, review it"

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

Treat the token like an API/SSH key. See SECURITY.md

Troubleshoot

hcom status   # diagnostics

hcom reset all   # clear and archive: database + hooks + config

Uninstall

Safely remove all hcom hooks:

hcom hooks remove

Then remove binary:

brew uninstall hcom
# or: uv tool 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`
Qoder CLI	automatic	`hcom qoder`
Grok Build	automatic	`hcom grok`
Hermes Agent	automatic	`hcom hermes`
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 prompt:

run 2x task tool and get them to talk to each other in hcom

Hermes chats

A Hermes gateway chat (Telegram, Discord, etc) can join hcom:

hcom hooks add hermes   # plugin into the active profile (HERMES_HOME picks another); a running gateway loads it

In the chat: /hcom start connects, /hcom stop disconnects.

hcom hooks remove hermes disconnects and removes its plugin.

CLI

CLI commands

What you might type from a shell. Agents run their own commands that they learn from the hcom CLI primer (~700 tokens) at launch. hcom <command> --help for full flags.

Spawn

hcom [N] claude|gemini|codex|agy|opencode|kilo|pi|omp|cursor-agent|kimi|copilot|qoder|grok|hermes   # launch N agents
hcom r <name|session_id>     # resume agent
hcom f <name|session_id>     # fork session
hcom kill <name|tag:T|all>   # kill + close terminal pane

hcom launch flags:

Flag	Purpose
`--tag <name>`	Group label — agents can be addressed as `@tag`
`--terminal <preset>`	Where windows open: `default` (auto-detect), `kitty`, `wezterm`, `tmux`, `cmux`, `iterm`, etc…
`--dir <path>`	Directory where the agent launches
`--headless`	Run in background pty with no terminal window
`--device <name>`	Spawn on a remote device (via relay)
`--hcom-prompt <text>`	Initial user prompt
`--hcom-system-prompt <text>`	Append to system prompt

Anything else is forwarded to the tool: --model sonnet, --yolo, etc.

Other commands

hcom                           # TUI dashboard
hcom send -b @luna -- hey      # one-off message to an agent
hcom list                      # show all active agents
hcom term [name]               # view/inject into an agent's PTY screen
hcom events --wait <filters>   # Block until match for scripting
hcom update                    # update hcom version

hcom run docs --cli for all commands.

Config

Configuration

Config lives in ~/.hcom/config.toml. Precedence: defaults < config.toml < env vars.

hcom config                           # show all values with sources
hcom config <key>                     # get
hcom config <key> <value>             # set
hcom config <key> --info              # detailed help for a key
hcom config -i <name> <key> <value>   # per-agent override at runtime

Keys

Key	Purpose
`tag`	Group label — launched agents become `tag-name`
`hints`	Text appended to every message the agent receives
`notes`	Text appended to bootstrap (one-time, at launch)
`auto_approve`	Auto-approve safe hcom commands (send/list/events/…)
`auto_subscribe`	Event subscription presets: `collision`, `created`, `stopped`, `blocked`
`name_export`	Export instance name to a custom env var
`title_mode`	Terminal/tab title behavior: `combined` (default), `label`, or `off`
`terminal`	Where new agent windows open (`hcom config terminal --info`)
`timeout`	Idle timeout for headless Claude (seconds)
`subagent_timeout`	Keep-alive for Claude subagents (seconds)
`claude_args` / `gemini_args` / `codex_args` / `opencode_args` / `kilo_args` / `pi_args` / `omp_args` / `cursor_args` / `kimi_args` / `copilot_args` / `qoder_args` / `grok_args` / `hermes_args`	Default args passed to the tool

Scope

hcom config tag mycrew                        # global
hcom config -i luna hints "respond in JSON"   # per-agent
HCOM_TAG=dev hcom 3 claude                    # per-launch env

Per-project isolation

export HCOM_DIR="$PWD/.hcom"   # isolate hcom state (db, logs) to this folder
rm -rf "$HCOM_DIR"             # clean up

Run hcom config <key> --info or hcom run docs --config for the full per-key reference.

Edit ~/.hcom/env to set external env vars passed to every launched agent.

Workflow Scripts

Multi-agent workflows

Bundled and user scripts (~/.hcom/scripts/) for multi-agent patterns:

hcom run                  # list available scripts
hcom run debate "topic"   # run one
hcom run docs             # tell agent to run this to create any new workflow

Included scripts

Tell agent to run them:

hcom run confess — An agent (or background clone) writes an honesty self-eval. A spawned calibrator reads the target's transcript independently. A judge compares both reports and sends back a verdict via hcom message.
hcom run debate — A judge spawns and sets up a debate with existing agents. It coordinates rounds in a shared thread where all agents see each other's arguments, with shared context of workspace files and transcripts.
hcom run fatcow — headless agent reads every file in a path, subscribes to file edit events to stay current, and answers other agents on demand.
hcom run onidle — waits for an agent to go idle, then types text into another agent (hcom run onidle luna nova 'luna is done, review it') or launches a new one with it as the prompt (hcom run onidle luna codex 'review what luna just did').

Custom scripts: drop *.sh or *.py into ~/.hcom/scripts/ — auto-discovered, override bundled scripts of the same name. Ask an agent to author one; hcom run docs --scripts is the authoring guide.

Contributing

Issues and PRs welcome. Build from source and dev setup: CONTRIBUTING.md

License

MIT

Metadata

Release files for hcom 0.7.30

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for hcom 0.7.30
File	Interpreter	ABI	Platform	Reset
hcom-0.7.30-py3-none-win_amd64.whl 7.9 MB Oct 15, 2026	Python 3	none	Windows x86-64	Details
hcom-0.7.30-py3-none-musllinux_1_2_x86_64.whl 7.4 MB Oct 15, 2026	Python 3	none	Linux musl 1.2+ x86-64	Details
hcom-0.7.30-py3-none-musllinux_1_2_aarch64.whl 6.7 MB Oct 15, 2026	Python 3	none	Linux musl 1.2+ ARM64	Details
hcom-0.7.30-py3-none-manylinux_2_28_aarch64.whl 6.5 MB Oct 15, 2026	Python 3	none	Linux glibc 2.28+ ARM64	Details
hcom-0.7.30-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 7.2 MB Oct 15, 2026	Python 3	none	Linux glibc 2.17+ x86-64	Details
hcom-0.7.30-py3-none-macosx_11_0_arm64.whl 6.5 MB Oct 15, 2026	Python 3	none	macOS 11.0+ ARM64	Details
hcom-0.7.30-py3-none-macosx_10_12_x86_64.whl 7.0 MB Oct 15, 2026	Python 3	none	macOS 10.12+ x86-64	Details
hcom-0.7.30-py3-none-android_24_arm64_v8a.whl 6.7 MB Oct 15, 2026	Python 3	none	Android API level 24+ ARM64 v8a	Details

Total release size: 56.1 MB

Release files / hcom-0.7.30-py3-none-win_amd64.whl

Download URL	hcom-0.7.30-py3-none-win_amd64.whl
Size	7.9 MB
Tags	Python 3 Windows x86-64
SHA-256 checksum How to use checksums	`e778a27e1bc457946856c4a8d96a6a39f42eb7e0e008a35840402f444da99ec7`
BLAKE2b-256 checksum How to use checksums	`8dfa0d7cfd9209e307ea6f7aa81542917a5c6c057248239ba703a5d225b45cfd`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-musllinux_1_2_x86_64.whl

Download URL	hcom-0.7.30-py3-none-musllinux_1_2_x86_64.whl
Size	7.4 MB
Tags	Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum How to use checksums	`989da49abef0104eda8e93f929793e6fca51c15b54bb8aed9041af40cc740ea6`
BLAKE2b-256 checksum How to use checksums	`ed7efe6478f0782565989bf78789b55afa32f11d25f90cc893f9e20170456601`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-musllinux_1_2_aarch64.whl

Download URL	hcom-0.7.30-py3-none-musllinux_1_2_aarch64.whl
Size	6.7 MB
Tags	Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum How to use checksums	`a37d431aa124c54a459c6070f7ef0a03192b3309e26d0fce5df5188078b17144`
BLAKE2b-256 checksum How to use checksums	`269a13ed004e5b585063afb51ab7118d71f7dad6397af6c9282b8a6b1c2d3695`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-manylinux_2_28_aarch64.whl

Download URL	hcom-0.7.30-py3-none-manylinux_2_28_aarch64.whl
Size	6.5 MB
Tags	Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum How to use checksums	`278202e8eedce8a838785be8153b26b36fee0662640fc838fc7048da01aaba81`
BLAKE2b-256 checksum How to use checksums	`f023e746ce90643a1286ed3c6410c66eaae7134fbd2267d002814e6a932a2b60`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	hcom-0.7.30-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	7.2 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`38b4424fb335cd6faa70010823682e53a4a2e29e31a36a977874a13f11ad0992`
BLAKE2b-256 checksum How to use checksums	`21fb0a48f19a1c39b4ff59412f1fe34130c14acbc55da69097018d729191c6d2`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-macosx_11_0_arm64.whl

Download URL	hcom-0.7.30-py3-none-macosx_11_0_arm64.whl
Size	6.5 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`764b6469ce4fe470094d2fb821285ea5e7e002726c68c634752663abe2410ea4`
BLAKE2b-256 checksum How to use checksums	`f5ed5e951b0e6fcadef1a2598e82b969b3eaa387a3e202f8987102d0e84cddfc`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-macosx_10_12_x86_64.whl

Download URL	hcom-0.7.30-py3-none-macosx_10_12_x86_64.whl
Size	7.0 MB
Tags	Python 3 macOS 10.12+ x86-64
SHA-256 checksum How to use checksums	`bb32f2e0357e067c03827fc3c8e1319d67874b7bc49977c5e69b95a11a2a9bfb`
BLAKE2b-256 checksum How to use checksums	`bac304dd3c68d87620fa347372b5e9450c3bb3518aa096abdf08169e6d2ce37f`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / hcom-0.7.30-py3-none-android_24_arm64_v8a.whl

Download URL	hcom-0.7.30-py3-none-android_24_arm64_v8a.whl
Size	6.7 MB
Tags	Android API level 24+ ARM64 v8a Python 3
SHA-256 checksum How to use checksums	`8f48dfbe77aa0e68ee18cd00b9221d52c161fe8e2ab5ece43885d233594bd24e`
BLAKE2b-256 checksum How to use checksums	`2110b8e352b656c3f2076252ea27f00abdc2d3735bacefafa584b0ec4b5e1484`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`