hcom
Let AI agents message, watch, and spawn each other across terminals. Claude Code, Codex, Antigravity CLI, Cursor CLI, OpenCode, Kilo, Pi, Kimi
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/aannoo--hcom)HTML
<a href="/listings/aannoo--hcom"><img src="/api/listings/aannoo--hcom/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**python -** macOS, Linux, Windows:
uv tool install hcom
**homebrew -** macOS, Linux:
brew install aannoo/hcom/hcom
<details> <summary>Other install options</summary>
# 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
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 21 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
- "name": "hcom",
- "version": "1.0.0",
- "description": "Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode, Kilo Code, Pi, Oh My Pi, Antigravity, Cursor, Kimi, Copilot, Qoder CLI, Grok Build.",
- "metadata": {
- "description": "Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode, Kilo Code, Pi, Oh My Pi, Antigravity, Cursor, Kimi, Copilot, Qoder CLI, Grok Build."
- },
- "owner": {
- "name": "aannoo"
- },
- "plugins": [
- {
- "name": "hcom",
- "source": "./plugin/hcom",
- "description": "Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode, Kilo Code, Pi, Oh My Pi, Antigravity, Cursor, Kimi, Copilot, Qoder CLI, Grok Build.",
- "category": "productivity",
- "homepage": "https://github.com/aannoo/hcom"
- }
- ]
- }
README.md · README · 392 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # hcom
- [](https://github.com/aannoo/hcom/actions/workflows/ci.yml) [](https://github.com/aannoo/hcom/releases) [](https://github.com/aannoo/hcom/blob/main/LICENSE)
- Connect independent coding agents across terminals and machines. They can message each other, monitor activity, react to events, and launch more agents. 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` `grok` `hermes` `pi` `omp` `agy` `copilot` `qoder` `cursor` `kimi` `kilo` `gemini`
- https://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43
- ## Install
- macOS, Linux, Windows:
- ```bash
- uv tool install hcom
- ```
- or: `brew install aannoo/hcom/hcom`
- <details>
- <summary>or install script</summary>
- <br>
- macOS, Linux, Android:
- ```bash
- curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
- ```
- Windows:
- ```powershell
- irm https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.ps1 | iex
- ```
- </details>
- ## Quickstart
- <table>
- <tr>
- <td width="50%" valign="top">
- **Terminal 1:**
- ```bash
- hcom claude
- ```
- </td>
- <td width="50%" valign="top">
- **Terminal 2:**
- ```bash
- hcom codex
- ```
- </td>
- </tr>
- </table>
- <b>Prompt:</b>
- <details>
- <summary><code>ask the other agent their favorite cake</code></summary>
- - `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`
- - `find the agent that worked on that feature, resume it and ask it why it's bad`
- </details>
- **Open the TUI dashboard:**
- ```bash
- hcom
- ```
- ## What agents can do
- - **Message** each other in real time. Messages arrive mid-turn (after tool calls) or wake idle agents immediately.
- - **Observe** who's running and what they're doing: status, transcripts, tool results, file edits, commands, live terminal screens, context/token usage. Search past conversations.
- - **Subscribe** to status changes, commands, file edits, collisions, and session events, then react automatically.
- - **Control**: spawn, fork, resume, kill agents in any terminal emulator or headless.
- ## How it works
- Hooks record activity to a local SQLite database and deliver messages from it.
- ```text
- agent → hooks → db → hooks → other agent
- ```
- Hooks activate only when an agent is launched with `hcom` in front. Normal usage is unaffected.
- <details>
- <summary>Any other AI tool without hooks can join by running <code>hcom start</code></summary>
- <br>
- In any CLI tool, prompt:
- ```text
- > run: `hcom start --help` follow what it says and stay connected
- ```
- </details>
- <details>
- <summary>Any process can wake agents with <code>hcom send</code></summary>
- <br>
- Send messages from any process/script:
- ```bash
- hcom send -b @luna -- "wake up and do this task"
- ```
- Chain with `hcom events`:
- ```bash
- hcom events --idle luna --wait 600 && hcom send -b @nova -- "luna is done, review it"
- ```
- </details>
- ## Terminals
- Every agent runs in a real terminal you can see, scroll, and interrupt. Any emulator works for spawning (hcom auto-detects). **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:
- ```bash
- hcom config terminal --info
- ```
- ## Cross-device
- Connect agents across machines via MQTT relay.
- ```bash
- hcom relay new # get token
- hcom relay connect <token> # on each device
- ```
- Check with `hcom relay status`, toggle with `hcom relay off` / `on`.
- > Treat the token like an API/SSH key. See [SECURITY.md](SECURITY.md)
- ---
- ## Reference
- Full reference: `hcom run docs`
- <details>
- <summary><strong>Tools</strong></summary>
- ### 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) |
- ```bash
- 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.
- ```bash
- 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:
- ```bash
- 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.
- </details>
- <details>
- <summary><strong>CLI</strong></summary>
- ### 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
- ```bash
- 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 |
- | `--json` | Print the outcome as one JSON object (also `hcom r`, `hcom f`, `hcom kill`); an error that stops the command before it acts goes to stderr with a non-zero exit and no JSON |
- Anything else is forwarded to the tool: `--model sonnet`, `--yolo`, etc.
- #### Other commands
- ```bash
- 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 events --follow # Stream events as JSON Lines
- hcom update # update hcom version
- ```
- `hcom run docs --cli` for all commands.
- </details>
- <details>
- <summary><strong>Config</strong></summary>
- ### Configuration
- Config lives in `~/.hcom/config.toml`. Precedence: defaults < `config.toml` < env vars.
- ```bash
- 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) |
- | `bootstrap_exclude` | Bootstrap parts to omit: `identity`, `messages`, `capabilities` (including tag, relay, headless, and command notices), `rules`, `handoff`, or `all` (default: `none`). Inspect with `hcom config bootstrap show [part]`. |
- | `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
- ```bash
- 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
- ```bash
- 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.
- </details>
- <details>
- <summary><strong>Workflow Scripts</strong></summary>
- ### Multi-agent workflows
- Bundled and user scripts (`~/.hcom/scripts/`) for multi-agent patterns:
- ```bash
- 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.
- </details>
- <details>
- <summary><strong>Troubleshoot and Uninstall</strong></summary>
- ### Troubleshoot
- ```bash
- hcom status # diagnostics
- ```
- ```bash
- hcom reset all # clear and archive: database + hooks + config
- ```
- ### Uninstall
- Safely remove all hcom hooks:
- ```bash
- hcom hooks remove
- ```
- Then remove binary:
- ```bash
- brew uninstall hcom
- # or: uv tool uninstall hcom
- # or: rm "$(which hcom)"
- ```
- </details>
- ## Contributing
- Issues and PRs welcome. Build from source and dev setup: [CONTRIBUTING.md](CONTRIBUTING.md)
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.