aannoo/hcom
Overview
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.
How this skill works
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.
When to use it
- You need to install or verify hcom and its hooks across terminals.
- Messages between agents are not arriving or agents are not listening.
- You want to connect Claude Code, Gemini CLI, or Codex agents so they can watch/spawn each other.
- You need to diagnose collisions or unexpected file edits from multiple agents.
- You want to run hcom in a project-local sandbox or check logs and database locations.
Best practices
- Run hcom status first to detect missing installs or hooks before troubleshooting further.
- Install hooks for each AI tool by running the tool via hcom (e.g., hcom claude) or hcom hooks add, then restart the tool.
- Use hcom list and hcom events to confirm recipient states and recent messages before assuming delivery failures.
- Set HCOM_DIR for project-local mode to avoid permission or sandbox restrictions and to keep data scoped to the repo.
- If things are inconsistent, run hcom reset all then re-add hooks and restart each tool to create a clean state.
Example use cases
- A developer asks “how to setup hcom” and follows install → hcom claude/gemini/codex → restart guide to enable hooks.
- Troubleshoot “hcom not working” by running hcom status, hooks status, daemon/relay status and following recommended fixes.
- Diagnose missing messages by checking hcom list for listener state and querying recent message events with hcom events --sql.
- Run hcom in project-local mode with HCOM_DIR to avoid sandbox restrictions when agents run in restricted environments.
- Detect and resolve file-edit collisions when two agents modify the same file within 20s and notify both agents for manual review.
FAQ
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.
2 skills
This skill coordinates Claude Code, Gemini CLI, and Codex across terminals to improve collaboration, reduce conflicts, and accelerate multi-agent workflows.
This skill helps you manage real-time agent communication and troubleshooting for hcom, enabling setup, status checks, and cross-device coordination.
