Metadata-Version: 2.4
Name: hcom
Version: 0.7.31
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Android
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
License-File: LICENSE
Summary: 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.
Keywords: claude,claude-code,gemini,codex,opencode,kilo,kilocode,pi,omp,oh-my-pi,antigravity,cursor,kimi,copilot,qoder,grok,grok-build,hooks,agents,cli,multi-agent,orchestration,terminal
Home-Page: https://github.com/aannoo/hcom
Author: aannoo
License-Expression: MIT
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/aannoo/hcom#readme
Project-URL: Homepage, https://github.com/aannoo/hcom
Project-URL: Issues, https://github.com/aannoo/hcom/issues
Project-URL: Repository, https://github.com/aannoo/hcom

# hcom

[![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)

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)

