hcom

Hook your coding agents together

This repository is a fork of aannoo/hcom. Its primary addition is the agent subcommand, providing persistent named agent catalogs, directory bundles, private agent skills, and multi-agent group launches.

hcom is a CLI that coding agents use to message, watch, and spawn each other across terminals. It integrates with Claude Code, Codex, OpenCode, Kilo Code, Pi, Oh My Pi, Antigravity, Cursor, Kimi, Gemini, 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.

hcom-video.mp4

Install

# macOS, Linux, Android (Termux), and WSL
curl -fsSL https://github.com/orgoj/hcom/releases/latest/download/hcom-installer.sh | sh

# Windows (native, PowerShell)
irm https://github.com/orgoj/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 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: 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. For hcom-requested work, agents send one reply only after the work is complete, then leave a short terminal summary instead of a blank terminal or a duplicate full report.

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.

With the Herdr preset, hcom supplies Herdr's native agent identity hint on Unix/macOS and uses native descendant-process detection on Windows. Herdr remains responsible for agent state through its screen manifests or installed integrations; hcom only supplies lifecycle reports for tools Herdr does not recognize.

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 --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

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 list                    # reconcile and show live agents
hcom list --stopped --all    # inspect stopped/stale history
hcom kill <name>             # remove one live managed instance
hcom reset all               # last resort: archive database, hooks, and config

For Instance '<name>' already exists after a reboot, run hcom list and retry. For newly launched agents, listing compares the recorded process incarnation—not just its reusable numeric PID—and immediately reconciles a process lost to exit or reboot. Older records retain heartbeat-based stale cleanup. Current releases also reconcile stale launch records automatically when reusing an explicit name.

Running another AI CLI directly from an hcom-managed agent is safe: foreign child hooks cannot reuse the parent's inherited process identity. If an older release already let a child overwrite a Claude instance's session metadata, the next Claude hook restores the original identity when both transcript paths identify the cross-tool mismatch.

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 prompt:

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

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|opencode|kilo|pi|omp|antigravity|cursor|kimi|copilot|hermes   # launch N agents
hcom r <name|session_id>                # resume agent
hcom f <name|session_id>                # fork session
hcom kill <name|@group|tag:T|all>          # kill + close terminal pane

hcom launch flags:

Flag	Purpose
`--as <name>`	Explicit agent name (single-agent launch only)
`--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>`	Invocation-local agent instructions (native channel or marked fallback)
`--dry-run`	Print the launch preview and run nothing (wins over `--go`)

Anything else is forwarded verbatim to the tool: --model sonnet, --yolo, etc. A flag hcom does not know is never an error here — it lands in the tool's argv, so a typo in an hcom flag surfaces as the tool's own "unknown option". -- ends hcom's flags explicitly, and --dry-run shows the resulting command without launching anything.

Named agents

hcom agent launches recurring agents from JSON settings and editable bundles. A bundle at ~/.hcom/agents/<name>/SOUL.md or an enclosing project .hcom/agents/<name>/SOUL.md defines an agent even without a JSON entry. Its contents follow the fixed system_prompt; immediate skills/*/SKILL.md children are advertised through one shared lazy-loading manifest. Both are reread on clean start and named resume. Bundle AGENTS.md files are not read as a fallback. For Antigravity, an external bundle is made writable with agy --add-dir. An instance name is unique: launching one that already runs prints its status and exits. Use --as to run the same definition concurrently.

hcom agent wdt_main                 # launch (or report that it already runs)
hcom agent @wdt                     # launch every member of a catalog group
hcom agent wdt_main --as wdt_review # same config, independent instance named wdt_review
hcom agent wdt_main --continue      # clean session with handoff summary from previous session
hcom agent wdt_main --cli claude --continue # switch tool (e.g. from Codex) with previous context
hcom agent wdt_main --cli codex     # unknown flags are forwarded to `hcom <cli>`
hcom agent list                     # catalog + effective CLI/model + live status + source
hcom agent list --for-agents        # only names and catalog "description" entries
hcom agent list @wdt                # show only members of one catalog group
hcom agent list --all               # include agents hidden by recursive selective imports
hcom agent list --local             # only direct and imported agents from this project
hcom agent show wdt_main            # effective model/reasoning and the exact command
hcom agent edit                     # open the catalog in $EDITOR (creates a starter file)

Targeted messages start missing or stopped catalog agents before delivery. The send waits briefly for that first event to be acknowledged; if startup is still settling, it succeeds with Queued; delivery pending and keeps the event durable for later delivery. Catalog precedence, imports, tool profiles, terminal placement, resume behavior, instruction transport, and bundle skills are documented in Named agents.

A catalog entry with "roaming": true is a project-local archetype. It omits dir, session, and window; hcom send @reviewer resolves the sender's nearest Git root (then the nearest .hcom/agents.json, then the sender directory), routes to reviewer_<project>, and starts that instance in the resolved root when needed. Different projects therefore get separate sessions. Catalog env is preserved during autostart, including an isolated policy such as "DIPPY_CONFIG_ONLY": "/path/to/reviewer.dippy". Broadcasts never materialize roaming agents.

The precedence chain is built-in defaults, global catalog defaults, each matching catalog's defaults and named entry, the matching tools.<cli> profile, then command-line flags. It is the same inside and outside a project. Later scalar values replace earlier ones: a project system_prompt replaces the global text rather than appending to it, and "" clears it. Recursive imports apply before the importing catalog's local entries, and a catalog's defaults also cover the agents it brings in, whether by import or as the enclosing project of a nested .hcom. An agent defined only in a project catalog is addressable from inside that project, and from elsewhere only where a catalog in scope imports it; a project's other agents stay private to it.

Catalog session/window placement is honored when Herdr is the configured default, including nested launches and targeted-message autostart; a parent agent's Herdr location is not inherited.

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 agent <name>                   # launch a named agent from the catalog
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/vanilla 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`	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 state + hooks to this folder
hcom hooks remove && rm -rf "$HCOM_DIR"

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.

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.

Build

Building from source

# Prerequisites: Rust 1.88+

git clone --branch orgoj https://github.com/orgoj/hcom.git
cd hcom
cargo build
cargo test

Using local build

Two options:

Symlink — simple, dev build is global.

ln -sf $(pwd)/target/debug/hcom ~/.cargo/bin/hcom

dev_root — works regardless of how hcom was installed (brew, pip, etc.); picks the newer of debug/release automatically:

hcom config dev_root $(pwd)
hcom config dev_root --unset  # revert
hcom status    # run local build

For concurrent worktrees, scope each to its own DB:

HCOM_DIR=$PWD/.hcom HCOM_DEV_ROOT=$PWD hcom claude

Contributing

Issues and PRs welcome. The codebase is Rust.

cargo build && cargo test
hcom config dev_root $(pwd)
hcom status
just ci  # run the CI gate locally

License

MIT

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.claude-plugin		.claude-plugin
.github		.github
docs		docs
plugin/hcom		plugin/hcom
scripts		scripts
skills/hcom-agent-messaging		skills/hcom-agent-messaging
src		src
tests		tests
.gitignore		.gitignore
.node-version		.node-version
AGENTS.md		AGENTS.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
IDEAS.md		IDEAS.md
Justfile		Justfile
LICENSE		LICENSE
README.md		README.md
dist-workspace.toml		dist-workspace.toml
gemini-extension.json		gemini-extension.json
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
rust-toolchain.toml		rust-toolchain.toml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

hcom

Install

Quickstart

What agents can do

How it works

Terminal

Cross-device

Security

Security model

What the token means

Limits by design

Storage

Incident response

Troubleshoot

Uninstall

Reference

Supported tools

Claude Code headless and subagents

CLI commands

Spawn

Named agents

Other commands

Configuration

Keys

Scope

Per-project isolation

Multi-agent workflows

Included scripts

Building from source

Using local build

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

hcom

Install

Quickstart

What agents can do

How it works

Terminal

Cross-device

Security

Security model

What the token means

Limits by design

Storage

Incident response

Troubleshoot

Uninstall

Reference

Supported tools

Claude Code headless and subagents

CLI commands

Spawn

Named agents

Other commands

Configuration

Keys

Scope

Per-project isolation

Multi-agent workflows

Included scripts

Building from source

Using local build

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages