Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aannoo--hcom/badge.svg)](/listings/aannoo--hcom)

HTML

<a href="/listings/aannoo--hcom"><img src="/api/listings/aannoo--hcom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. {
  2. "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
  3. "name": "hcom",
  4. "version": "1.0.0",
  5. "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.",
  6. "metadata": {
  7. "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."
  8. },
  9. "owner": {
  10. "name": "aannoo"
  11. },
  12. "plugins": [
  13. {
  14. "name": "hcom",
  15. "source": "./plugin/hcom",
  16. "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.",
  17. "category": "productivity",
  18. "homepage": "https://github.com/aannoo/hcom"
  19. }
  20. ]
  21. }
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.

  1. # hcom
  2. [![CI](https://github.com/aannoo/hcom/actions/workflows/ci.yml/badge.svg)](https://github.com/aannoo/hcom/actions/workflows/ci.yml) [![Latest release](https://img.shields.io/github/v/release/aannoo/hcom)](https://github.com/aannoo/hcom/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/aannoo/hcom/blob/main/LICENSE)
  3. 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.
  4. Use it to coordinate multi-agent pipelines, run different AI CLIs as each other's subagents, or just to avoid copy-pasting.
  5. Works with `claude` `codex` `opencode` `grok` `hermes` `pi` `omp` `agy` `copilot` `qoder` `cursor` `kimi` `kilo` `gemini`
  6. https://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43
  7. ## Install
  8. macOS, Linux, Windows:
  9. ```bash
  10. uv tool install hcom
  11. ```
  12. or: `brew install aannoo/hcom/hcom`
  13. <details>
  14. <summary>or install script</summary>
  15. <br>
  16. macOS, Linux, Android:
  17. ```bash
  18. curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh
  19. ```
  20. Windows:
  21. ```powershell
  22. irm https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.ps1 | iex
  23. ```
  24. </details>
  25. ## Quickstart
  26. <table>
  27. <tr>
  28. <td width="50%" valign="top">
  29. **Terminal 1:**
  30. ```bash
  31. hcom claude
  32. ```
  33. </td>
  34. <td width="50%" valign="top">
  35. **Terminal 2:**
  36. ```bash
  37. hcom codex
  38. ```
  39. </td>
  40. </tr>
  41. </table>
  42. <b>Prompt:</b>
  43. <details>
  44. <summary><code>ask the other agent their favorite cake</code></summary>
  45. - `review what claude did and send it fixes`
  46. - `spawn 3x opencode, split work, collect results`
  47. - `fork yourself to investigate the bug and report back`
  48. - `when codex goes idle, send it the next task`
  49. - `find the agent that worked on that feature, resume it and ask it why it's bad`
  50. </details>
  51. **Open the TUI dashboard:**
  52. ```bash
  53. hcom
  54. ```
  55. ## What agents can do
  56. - **Message** each other in real time. Messages arrive mid-turn (after tool calls) or wake idle agents immediately.
  57. - **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.
  58. - **Subscribe** to status changes, commands, file edits, collisions, and session events, then react automatically.
  59. - **Control**: spawn, fork, resume, kill agents in any terminal emulator or headless.
  60. ## How it works
  61. Hooks record activity to a local SQLite database and deliver messages from it.
  62. ```text
  63. agent → hooks → db → hooks → other agent
  64. ```
  65. Hooks activate only when an agent is launched with `hcom` in front. Normal usage is unaffected.
  66. <details>
  67. <summary>Any other AI tool without hooks can join by running <code>hcom start</code></summary>
  68. <br>
  69. In any CLI tool, prompt:
  70. ```text
  71. > run: `hcom start --help` follow what it says and stay connected
  72. ```
  73. </details>
  74. <details>
  75. <summary>Any process can wake agents with <code>hcom send</code></summary>
  76. <br>
  77. Send messages from any process/script:
  78. ```bash
  79. hcom send -b @luna -- "wake up and do this task"
  80. ```
  81. Chain with `hcom events`:
  82. ```bash
  83. hcom events --idle luna --wait 600 && hcom send -b @nova -- "luna is done, review it"
  84. ```
  85. </details>
  86. ## Terminals
  87. 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`.
  88. To configure a custom terminal open/close setup, tell an agent to run:
  89. ```bash
  90. hcom config terminal --info
  91. ```
  92. ## Cross-device
  93. Connect agents across machines via MQTT relay.
  94. ```bash
  95. hcom relay new # get token
  96. hcom relay connect <token> # on each device
  97. ```
  98. Check with `hcom relay status`, toggle with `hcom relay off` / `on`.
  99. > Treat the token like an API/SSH key. See [SECURITY.md](SECURITY.md)
  100. ---
  101. ## Reference
  102. Full reference: `hcom run docs`
  103. <details>
  104. <summary><strong>Tools</strong></summary>
  105. ### Supported tools
  106. | Tool | Message delivery | Connect |
  107. |---|---|---|
  108. | Claude Code | automatic | `hcom claude` |
  109. | Gemini CLI | automatic | `hcom gemini` |
  110. | Codex CLI | automatic | `hcom codex` |
  111. | Antigravity CLI | automatic | `hcom agy` |
  112. | OpenCode | automatic | `hcom opencode` |
  113. | Kilo Code | automatic | `hcom kilo` |
  114. | Pi | automatic | `hcom pi` |
  115. | Oh My Pi | automatic | `hcom omp` |
  116. | Cursor CLI | automatic | `hcom cursor-agent` |
  117. | Kimi | automatic | `hcom kimi` |
  118. | Copilot CLI | automatic | `hcom copilot` |
  119. | Qoder CLI | automatic | `hcom qoder` |
  120. | Grok Build | automatic | `hcom grok` |
  121. | Hermes Agent | automatic | `hcom hermes` |
  122. | Anything else | manual via `hcom listen` | `hcom start` (run inside tool) |
  123. ```bash
  124. hcom r <session_id> # Resume a session started outside hcom
  125. hcom f <session_id> # Fork a session in hcom
  126. ```
  127. #### Claude Code headless and subagents
  128. Detached background processes in print mode stay alive. Manage through the TUI.
  129. ```bash
  130. hcom claude -p 'say hi in hcom' # print mode (separate Agent SDK credits)
  131. hcom claude --headless # Run normal claude in background pty (works for any tool)
  132. ```
  133. For subagents, run `hcom claude`, then prompt:
  134. > run 2x task tool and get them to talk to each other in hcom
  135. #### Hermes chats
  136. A Hermes gateway chat (Telegram, Discord, etc) can join hcom:
  137. ```bash
  138. hcom hooks add hermes # plugin into the active profile (HERMES_HOME picks another); a running gateway loads it
  139. ```
  140. In the chat: `/hcom start` connects, `/hcom stop` disconnects.
  141. `hcom hooks remove hermes` disconnects and removes its plugin.
  142. </details>
  143. <details>
  144. <summary><strong>CLI</strong></summary>
  145. ### CLI commands
  146. 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.
  147. #### Spawn
  148. ```bash
  149. hcom [N] claude|gemini|codex|agy|opencode|kilo|pi|omp|cursor-agent|kimi|copilot|qoder|grok|hermes # launch N agents
  150. hcom r <name|session_id> # resume agent
  151. hcom f <name|session_id> # fork session
  152. hcom kill <name|tag:T|all> # kill + close terminal pane
  153. ```
  154. hcom launch flags:
  155. | Flag | Purpose |
  156. |---|---|
  157. | `--tag <name>` | Group label — agents can be addressed as `@tag` |
  158. | `--terminal <preset>` | Where windows open: `default` (auto-detect), `kitty`, `wezterm`, `tmux`, `cmux`, `iterm`, etc… |
  159. | `--dir <path>` | Directory where the agent launches |
  160. | `--headless` | Run in background pty with no terminal window |
  161. | `--device <name>` | Spawn on a remote device (via relay) |
  162. | `--hcom-prompt <text>` | Initial user prompt |
  163. | `--hcom-system-prompt <text>` | Append to system prompt |
  164. | `--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 |
  165. Anything else is forwarded to the tool: `--model sonnet`, `--yolo`, etc.
  166. #### Other commands
  167. ```bash
  168. hcom # TUI dashboard
  169. hcom send -b @luna -- hey # one-off message to an agent
  170. hcom list # show all active agents
  171. hcom term [name] # view/inject into an agent's PTY screen
  172. hcom events --wait <filters> # Block until match for scripting
  173. hcom events --follow # Stream events as JSON Lines
  174. hcom update # update hcom version
  175. ```
  176. `hcom run docs --cli` for all commands.
  177. </details>
  178. <details>
  179. <summary><strong>Config</strong></summary>
  180. ### Configuration
  181. Config lives in `~/.hcom/config.toml`. Precedence: defaults < `config.toml` < env vars.
  182. ```bash
  183. hcom config # show all values with sources
  184. hcom config <key> # get
  185. hcom config <key> <value> # set
  186. hcom config <key> --info # detailed help for a key
  187. hcom config -i <name> <key> <value> # per-agent override at runtime
  188. ```
  189. #### Keys
  190. | Key | Purpose |
  191. |---|---|
  192. | `tag` | Group label — launched agents become `tag-name` |
  193. | `hints` | Text appended to every message the agent receives |
  194. | `notes` | Text appended to bootstrap (one-time, at launch) |
  195. | `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]`. |
  196. | `auto_approve` | Auto-approve safe hcom commands (send/list/events/…) |
  197. | `auto_subscribe` | Event subscription presets: `collision`, `created`, `stopped`, `blocked` |
  198. | `name_export` | Export instance name to a custom env var |
  199. | `title_mode` | Terminal/tab title behavior: `combined` (default), `label`, or `off` |
  200. | `terminal` | Where new agent windows open (`hcom config terminal --info`) |
  201. | `timeout` | Idle timeout for headless Claude (seconds) |
  202. | `subagent_timeout` | Keep-alive for Claude subagents (seconds) |
  203. | `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 |
  204. #### Scope
  205. ```bash
  206. hcom config tag mycrew # global
  207. hcom config -i luna hints "respond in JSON" # per-agent
  208. HCOM_TAG=dev hcom 3 claude # per-launch env
  209. ```
  210. #### Per-project isolation
  211. ```bash
  212. export HCOM_DIR="$PWD/.hcom" # isolate hcom state (db, logs) to this folder
  213. rm -rf "$HCOM_DIR" # clean up
  214. ```
  215. Run `hcom config <key> --info` or `hcom run docs --config` for the full per-key reference.
  216. Edit `~/.hcom/env` to set external env vars passed to every launched agent.
  217. </details>
  218. <details>
  219. <summary><strong>Workflow Scripts</strong></summary>
  220. ### Multi-agent workflows
  221. Bundled and user scripts (`~/.hcom/scripts/`) for multi-agent patterns:
  222. ```bash
  223. hcom run # list available scripts
  224. hcom run debate "topic" # run one
  225. hcom run docs # tell agent to run this to create any new workflow
  226. ```
  227. #### Included scripts
  228. Tell agent to run them:
  229. - **`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.
  230. - **`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.
  231. - **`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.
  232. - **`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'`).
  233. 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.
  234. </details>
  235. <details>
  236. <summary><strong>Troubleshoot and Uninstall</strong></summary>
  237. ### Troubleshoot
  238. ```bash
  239. hcom status # diagnostics
  240. ```
  241. ```bash
  242. hcom reset all # clear and archive: database + hooks + config
  243. ```
  244. ### Uninstall
  245. Safely remove all hcom hooks:
  246. ```bash
  247. hcom hooks remove
  248. ```
  249. Then remove binary:
  250. ```bash
  251. brew uninstall hcom
  252. # or: uv tool uninstall hcom
  253. # or: rm "$(which hcom)"
  254. ```
  255. </details>
  256. ## Contributing
  257. Issues and PRs welcome. Build from source and dev setup: [CONTRIBUTING.md](CONTRIBUTING.md)
  258. ## License
  259. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.