hcom-agent-messaging_skill

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.