{"id":42180210,"url":"https://github.com/aannoo/hcom","last_synced_at":"2026-04-18T12:04:52.853Z","repository":{"id":305795209,"uuid":"1023335896","full_name":"aannoo/hcom","owner":"aannoo","description":"Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode","archived":false,"fork":false,"pushed_at":"2026-03-02T15:41:16.000Z","size":44361,"stargazers_count":102,"open_issues_count":4,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-02T18:57:11.975Z","etag":null,"topics":["agent","agent-skills","ai","ai-agents","ai-tools","automation","claude","claude-code","claude-code-hooks","cli","codex","coding-agent","communication","developer-tools","gemini-cli","multi-agent","opencode","orchestration","subagents","terminal"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/hcom/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aannoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-21T02:32:38.000Z","updated_at":"2026-03-02T16:14:19.000Z","dependencies_parsed_at":"2025-07-22T04:21:41.106Z","dependency_job_id":"e5f71259-1381-4a54-ace8-e7dfcd9e63b3","html_url":"https://github.com/aannoo/hcom","commit_stats":null,"previous_names":["aannoo/claude-hook-comms","aannoo/hcom"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/aannoo/hcom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aannoo%2Fhcom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aannoo%2Fhcom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aannoo%2Fhcom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aannoo%2Fhcom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aannoo","download_url":"https://codeload.github.com/aannoo/hcom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aannoo%2Fhcom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30326908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-skills","ai","ai-agents","ai-tools","automation","claude","claude-code","claude-code-hooks","cli","codex","coding-agent","communication","developer-tools","gemini-cli","multi-agent","opencode","orchestration","subagents","terminal"],"created_at":"2026-01-26T22:02:20.781Z","updated_at":"2026-04-18T12:04:52.841Z","avatar_url":"https://github.com/aannoo.png","language":"Rust","readme":"# hcom\n\n[![PyPI](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Rust](https://img.shields.io/badge/Built_with-Rust-dea584)](https://www.rust-lang.org/)\n[![GitHub stars](https://img.shields.io/github/stars/aannoo/hcom)](https://github.com/aannoo/hcom/stargazers)\n\n\u003e **Hook your coding agents together**\n\nPrefix agents with `hcom` to let them message, watch, and spawn each other across terminals.\n\nhttps://github.com/user-attachments/assets/1ce23ed9-f529-4be0-8124-816aa4c2fd43\n\n---\n\n## Install\n\n```bash\nbrew install aannoo/hcom/hcom\n```\n\n\u003cdetails\u003e\u003csummary\u003eOther install options\u003c/summary\u003e\n\n```bash\n# Shell installer for macOS, Linux, Android (Termux), and WSL\ncurl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh\n```\n\n```bash\n# With PyPI\nuv tool install hcom  # or: pip install hcom\n```\n\n\u003c/details\u003e\n\n---\n\n## Quickstart\n\n```bash\nhcom claude  # gemini / codex / opencode\n```\n\nPrompt:\n\n- `send a message to codex`\n- `review what claude did and send fixes`\n- `spawn 3x gemini, split work, collect results`\n- `fork yourself to investigate the bug and report back`\n\nOpen the TUI:\n\n```bash\nhcom\n```\n\n---\n\n## What agents can do\n\n**Message** each other in real-time, bundle context for handoffs.\n\n**Observe** each other: transcripts, file edits, terminal screens, command history.\n\n**Subscribe** to each other: notify on status changes, file edits, specific events. React automatically.\n\n**Spawn**, **fork**, **resume**, **kill** each other, in any terminal emulator.\n\n---\n\n## How it works\n\nHooks record activity to a local SQLite database and deliver messages from it.\n\n```bash\nagent → hooks → db → hooks → other agent\n```\n\nFor **Claude Code**, **Gemini CLI**, **Codex**, and **OpenCode**, messages arrive mid-turn (injected between tool calls) or wake idle agents immediately. Any other AI tool can join by running `hcom start`. Any process can wake agents with `hcom send`.\n\nCollision detection is on by default: if two agents edit the same file within 30 seconds, both get notified.\n\nHooks go into tool config dirs under `~/` (or `HCOM_DIR`) on first run. If you aren't using hcom, the hooks do nothing.\n\n---\n\n## Terminal\n\nEvery agent runs in a real terminal you can see, scroll, and interrupt. Any emulator works for spawning; **kitty**, **wezterm**, and **tmux** additionally support closing panes from `hcom kill`.\n\nTo configure a custom terminal open/close setup, tell agent to run:\n\n```bash\nhcom config terminal --info\n```\n\n---\n\n## Cross-device\n\nConnect agents across machines via MQTT relay.\n\n```bash\nhcom relay new                 # get token\nhcom relay connect \u003ctoken\u003e     # on each device\n```\n\n```bash\nhcom relay status              # check connection\nhcom relay off|on              # toggle\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eRelay Security\u003c/summary\u003e\n\n### Security\n\n- Relay payloads are end-to-end encrypted. Brokers do not see data.\n- Treat the join token like an SSH key or API key.\n- If the token may have leaked, run `hcom relay off --all` to disconnect all devices.\n- Use a private/custom/self-hosted broker with `--broker` and `--password` for better security.\n\n### Security model\n\n`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.\n\nRelay 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.\n\nBrokers and network observers cannot read or forge payloads without the PSK. They can still see metadata: topic names, timing, message sizes, and connection patterns.\n\n### What the token means\n\nThe 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.\n\nOn 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.\n\nOn 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.\n\n### Limits by design\n\n- Forward secrecy. A leaked PSK can decrypt old captured traffic.\n- Per-device attribution inside a relay. Sender identity is routing metadata, not authorization. Every enrolled device speaks with full authority.\n- 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.\n- 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.\n\n### Storage\n\nThe PSK is stored in `~/.hcom/config.toml`. On Unix, hcom writes that file with mode `0600`.\n\nhcom 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.\n\nAnyone who can read that file — another user on the same OS account, malware, or a backup written without preserving permissions — has the full PSK.\n\n### Incident response\n\nRun `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.\n\nThe 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.\n\nTo 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.\n\n\u003c/details\u003e\n\n---\n\n## Troubleshoot\n\n```bash\nhcom status           # diagnostics\nhcom reset all        # clear and archive: database + hooks + config\nhcom run docs         # tell agent to run\n```\n\n---\n\n## Uninstall\n\n```bash\nhcom hooks remove                     # safely remove all hcom hooks\nbrew uninstall hcom                   # or: rm $(which hcom)\n```\n\n---\n\n## Reference\n\n\u003cdetails\u003e\n\u003csummary\u003eTools\u003c/summary\u003e\n\n### Supported tools\n\n| Tool | Message delivery | Connect |\n|---|---|---|\n| Claude Code | automatic | `hcom claude` |\n| Gemini CLI | automatic | `hcom gemini` |\n| Codex CLI | automatic | `hcom codex` |\n| OpenCode | automatic | `hcom opencode` |\n| Anything else | manual via `hcom listen` | `hcom start` (run inside tool) |\n\n```bash\nhcom r \u003csession_id\u003e           # Resume a session started outside hcom\nhcom f \u003csession_id\u003e           # Fork a session in hcom\n```\n\n#### Claude Code headless and subagents\n\nDetached background processes in print mode stay alive. Manage through the TUI.\n\n```bash\nhcom claude -p 'say hi in hcom'\n```\n\nFor subagents, run `hcom claude`, then prompt:\n\n\u003e run 2x task tool and get them to talk to each other in hcom\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eCLI\u003c/summary\u003e\n\n### CLI commands\n\nWhat you might type from a shell. Agents run their own commands that they learn from the hcom CLI primer (~700 tokens) at launch. `hcom \u003ccommand\u003e --help` for full flags.\n\n### Spawn\n\n```bash\nhcom [N] claude|gemini|codex|opencode   # launch N agents\nhcom r \u003cname|session_id\u003e                # resume agent\nhcom f \u003cname|session_id\u003e                # fork session\nhcom kill \u003cname|tag:T|all\u003e              # kill + close terminal pane\n```\n\nhcom launch flags:\n\n| Flag | Purpose |\n|---|---|\n| `--tag \u003cname\u003e` | Group label — agents can be addressed as `@tag` |\n| `--terminal \u003cpreset\u003e` | Where windows open: `default` (auto-detect), `kitty`, `wezterm`, `tmux`, `cmux`, `iterm`, etc… |\n| `--dir \u003cpath\u003e` | Directory where the agent launches |\n| `--headless` | Run in background with no terminal window |\n| `--device \u003cname\u003e` | Spawn on a remote device (via relay) |\n| `--hcom-prompt \u003ctext\u003e` | Initial user prompt |\n| `--hcom-system-prompt \u003ctext\u003e` | Append to system prompt |\n\nAnything else is forwarded to the tool: `--model sonnet`, `--yolo`, etc.\n\n### Other commands\n\n```bash\nhcom                                # TUI dashboard\nhcom send -b @luna -- hey           # one-off message to an agent\nhcom list                           # show all active agents\nhcom term [name]                    # view/inject into an agent's PTY screen\nhcom events --wait \u003cfilters\u003e         # Block until match for scripting\nhcom update                         # update hcom version\n```\n\n`hcom --help` for all commands.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eConfig\u003c/summary\u003e\n\n### Configuration\n\nConfig lives in `~/.hcom/config.toml`. Precedence: defaults \u003c `config.toml` \u003c env vars.\n\n```bash\nhcom config                       # show all values with sources\nhcom config \u003ckey\u003e                 # get\nhcom config \u003ckey\u003e \u003cvalue\u003e         # set\nhcom config \u003ckey\u003e --info          # detailed help for a key\nhcom config -i \u003cname|self\u003e ...    # per-agent override at runtime\n```\n\n### Keys\n\n| Key | Purpose |\n|---|---|\n| `tag` | Group label — launched agents become `tag-name` |\n| `hints` | Text appended to every message the agent receives |\n| `notes` | Text appended to bootstrap (one-time, at launch) |\n| `auto_approve` | Auto-approve safe hcom commands (send/list/events/…) |\n| `auto_subscribe` | Event subscription presets: `collision`, `created`, `stopped`, `blocked` |\n| `name_export` | Export instance name to a custom env var |\n| `terminal` | Where new agent windows open (`hcom config terminal --info`) |\n| `timeout` | Idle timeout for headless/vanilla Claude (seconds) |\n| `subagent_timeout` | Keep-alive for Claude subagents (seconds) |\n| `claude_args` / `gemini_args` / `codex_args` / `opencode_args` | Default args passed to the tool |\n\n### Scope\n\n```bash\nhcom config tag mycrew                          # global\nhcom config -i luna hints \"respond in JSON\"     # per-agent\nHCOM_TAG=dev hcom 3 claude                      # per-launch env\n```\n\n### Per-project isolation\n\n```bash\nexport HCOM_DIR=\"$PWD/.hcom\"    # isolate state + hooks to this folder\nhcom hooks remove \u0026\u0026 rm -rf \"$HCOM_DIR\"\n```\n\nRun `hcom config \u003ckey\u003e --info` or `hcom run docs --config` for the full per-key reference.\n\nEdit `~/.hcom/env` to set external env vars passed to every launched agent.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWorkflow Scripts\u003c/summary\u003e\n\n### Multi-agent workflows\n\nBundled and user scripts (`~/.hcom/scripts/`) for multi-agent patterns:\n\n```bash\nhcom run                   # list available scripts\nhcom run debate \"topic\"    # run one\nhcom run docs              # tell agent to run this to create any new workflow\n```\n\n### Included Scripts\n\nTell agent to run them:\n\n**`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.\n\n**`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.\n\n**`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.\n\nCustom 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild\u003c/summary\u003e\n\n### Building from Source\n\n```bash\n# Prerequisites: Rust 1.86+\n\ngit clone https://github.com/aannoo/hcom.git\ncd hcom\ncargo test\ncargo build\n```\n\n### Using local build\n\nTwo options:\n\n**Symlink** — simple, dev build is global.\n\n```bash\nln -sf $(pwd)/target/debug/hcom ~/.cargo/bin/hcom\n```\n\n**dev_root** — works regardless of how hcom was installed (brew, pip, etc.); picks the newer of debug/release automatically:\n\n```bash\nhcom config dev_root $(pwd)\nhcom config dev_root --unset  # revert\nhcom -v    # run local build\n```\n\nFor concurrent worktrees, scope each to its own DB:\n\n```bash\nHCOM_DIR=$PWD/.hcom HCOM_DEV_ROOT=$PWD hcom claude\n```\n\n\u003c/details\u003e\n\n\n---\n\n## Contributing\n\nIssues and PRs welcome. The codebase is Rust.\n\n```bash\ncargo test \u0026\u0026 cargo build\nhcom config dev_root $(pwd)\nhcom -v\n```\n\n---\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["Multi-Agent \u0026 Orchestration",":tada: New","Frameworks","Applications"],"sub_categories":["Other IDEs","Productivity"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faannoo%2Fhcom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faannoo%2Fhcom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faannoo%2Fhcom/lists"}