home / skills / aannoo / hcom / hcom-agent-messaging
This skill coordinates Claude Code, Gemini CLI, and Codex across terminals to improve collaboration, reduce conflicts, and accelerate multi-agent workflows.
npx playbooks add skill aannoo/hcom --skill hcom-agent-messagingReview the files below or copy the command above to add this skill to your agents.
---
name: hcom-agent-messaging
description: |
Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode. Use this skill when the human user needs help, status, or reference about hcom - when user asks questions like "how to setup hcom", "hcom not working", "explain hcom", or any hcom troubleshooting.
---
# hcom — Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode.
AI agents running in separate terminals are isolated from each other. Context doesn't transfer, decisions get repeated, file edits collide. hcom connects them.
```
pip install hcom
hcom claude
hcom gemini
hcom codex
hcom opencode
hcom # TUI dashboard
```
---
## What humans can do
Tell any agent:
> send a message to claude
> when codex goes idle send it the next task
> watch gemini's file edits, review each and send feedback if any bugs
> fork yourself to investigate the bug and report back
> find which agent worked on terminal_id code, resume them and ask why it sucks
---
## What agents can do
- Message each other (@mentions, intents, threads, broadcast)
- Read each other's transcripts (ranges, detail levels)
- View agent terminal screens, inject text/enter for approvals
- Query event history (file edits, commands, status, lifecycle)
- Subscribe and react to each other's activity in real-time
- Spawn, fork, resume, kill agents in new terminal panes
- Build context bundles (files, transcript, events) for handoffs
- Collision detection — 2 agents edit same file within 20s, both notified
- Cross-device — connect agents across machines via MQTT relay
---
## Setup
If the user invokes this skill without arguments:
1. Run `hcom status` — if "command not found", run `pip install hcom` first
2. Tell user to run `hcom claude` or `hcom gemini` or `hcom codex` or `hcom opencode` in a new terminal (auto installs hooks on first run)
| Status Output | Meaning | Action |
|--------|---------|--------|
| command not found | hcom not installed | `pip install hcom` |
| `[~] claude` | Tool exists, hooks not installed | `hcom hooks add` then restart tool (or just `hcom claude`) |
| `[✓] claude` | Hooks installed | Ready — use `hcom claude` or `hcom start` |
| `[✗] claude` | Tool not found | Install the AI tool first |
After adding hooks or installing hcom you must restart the current AI tool for hcom to activate.
---
## Tool Support
| Tool | Message Delivery |
|------|------------------|
| Claude Code (incl. subagents) | automatic |
| Gemini CLI | automatic |
| Codex | automatic |
| OpenCode | automatic |
| Any AI tool | manual - via `hcom start` |
---
## Troubleshooting
### "hcom not working"
```bash
hcom status # Check installation
hcom hooks status # Check hooks specifically
hcom daemon status
hcom relay status
```
**Hooks missing?** `hcom hooks add` then restart tool.
**Still broken?**
```bash
hcom reset all && hcom hooks add
# Close all claude/codex/gemini/opencode/hcom windows
hcom claude # Fresh start
```
### "messages not arriving"
1. **Check recipient:** `hcom list` — are they `listening` or `active`?
2. **Check message sent:** `hcom events --sql "type='message'" --last 5`
3. **Recipient shows `[claude*]`?** Restart the AI tool
### Sandbox / Permission Issues
```bash
export HCOM_DIR="$PWD/.hcom" # Project-local mode
hcom hooks add # Installs to project dir
```
---
## Files
| What | Location |
|------|----------|
| Database | `~/.hcom/hcom.db` |
| Config | `~/.hcom/config.toml` |
| Logs | `~/.hcom/.tmp/logs/hcom.log` |
With `HCOM_DIR` set, uses that path instead of `~/.hcom`.
---
## More Info
```bash
hcom --help # All commands
hcom <command> --help # Command details
hcom run docs # Full CLI + config + API reference
```
GitHub: https://github.com/aannoo/hcom
This skill helps humans set up, monitor, and troubleshoot hcom — a bridge that lets Claude Code, Gemini CLI, and Codex agents message, watch, and spawn each other across terminals. It guides installation, hook management, status checks, and common fixes so multi-agent workflows stay synchronized and avoid collisions. Use it when you need status, setup instructions, or troubleshooting steps for hcom.
The skill runs diagnostic commands (hcom status, hooks status, daemon/relay status) and interprets their outputs to recommend actions. It explains how to install hcom, add hooks for specific tools, restart agents, and reset state. It also walks through message delivery checks, event queries, and sandbox configuration using HCOM_DIR.
What to run first if hcom commands return command not found?
Install hcom with pip install hcom, then re-run hcom status.
Hooks appear missing for a tool — how do I enable them?
Run hcom hooks add for global install or start the tool via hcom (e.g., hcom claude) which auto-installs hooks on first run, then restart the tool.
Messages are not arriving — how do I inspect delivery?
Check recipient state with hcom list, then inspect recent message events with hcom events --sql "type='message'" --last 5; restart the recipient tool if it shows a starred or partial state.
How do I run hcom locally per project to avoid permission issues?
Set HCOM_DIR="$PWD/.hcom" before adding hooks; hcom will use that directory for DB, config, and logs.