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, pi, omp, agy, cursor, kimi, kilo, gemini
hcom-video.mp4
python - macOS, Linux, Windows:
uv tool install hcomhomebrew - macOS, Linux:
brew install aannoo/hcom/hcomOther 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|
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-
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.
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"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 --infoConnect agents across machines via MQTT relay.
hcom relay new # get token
hcom relay connect <token> # on each devicehcom relay status # check connection
hcom relay off|on # toggleTreat the token like an API/SSH key. See SECURITY.md
hcom status # diagnosticshcom reset all # clear and archive: database + hooks + configSafely remove all hcom hooks:
hcom hooks removeThen remove binary:
brew uninstall hcom
# or: uv tool uninstall hcom
# or: rm "$(which hcom)"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 |
| 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 hcomDetached 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
CLI
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.
hcom [N] claude|gemini|codex|agy|opencode|kilo|pi|omp|cursor-agent|kimi|copilot|qoder|grok # 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 panehcom 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.
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 versionhcom run docs --cli for all commands.
Config
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| 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 |
Default args passed to the tool |
hcom config tag mycrew # global
hcom config -i luna hints "respond in JSON" # per-agent
HCOM_TAG=dev hcom 3 claude # per-launch envexport HCOM_DIR="$PWD/.hcom" # isolate hcom state (db, logs) to this folder
rm -rf "$HCOM_DIR" # clean upRun 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
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 workflowTell 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.
Issues and PRs welcome. Build from source and dev setup: CONTRIBUTING.md