{"id":"9eea4bb0-b400-43d4-a5eb-5b1d24e97a17","shortId":"CEpHKV","kind":"skill","title":"hcom-agent-messaging","tagline":"Multi-agent communication for AI coding tools. Agents message, watch, and spawn each other across terminals. Use when setting up hcom, troubleshooting delivery, or writing multi-agent scripts.","description":"# hcom — multi-agent communication for AI coding tools\n\nAI agents running in separate terminals are isolated. hcom connects them via hooks and a shared database so they can message, watch, and spawn each other in real-time.\n\n```bash\ncurl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh\nhcom claude       # or: hcom gemini, hcom codex, hcom opencode\nhcom              # TUI dashboard\n```\n\n---\n\n## what humans can do\n\ntell any agent:\n\n> send a message to claude\n\n> when codex goes idle send it the next task\n\n> watch gemini's file edits, review each and send feedback if any bugs\n\n> fork yourself to investigate the bug and report back\n\n> find which agent worked on terminal_id code, resume them and ask why it sucks\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\nrun `hcom --help` for full command syntax and flags.\n\n---\n\n## tool support\n\n| tool | delivery | connect |\n|------|----------|---------|\n| claude code (incl. subagents) | automatic | `hcom claude` |\n| gemini cli (>= 0.26.0) | automatic | `hcom gemini` |\n| codex | automatic | `hcom codex` |\n| opencode | automatic | `hcom opencode` |\n| any other ai tool | manual via `hcom listen` | `hcom start` (run inside tool) |\n\nsession binding (hcom transcript, hcom r/f by session id) happens on first message or first prompt for all hcom-launched tools.\n\n---\n\n## setup\n\nif the user invokes this skill without arguments:\n\n1. run `hcom status` — if \"command not found\", install first:\n   ```bash\n   curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh\n   ```\n2. run `hcom hooks add` to install hooks for all detected tools\n3. restart the AI tool for hooks to activate\n\n| status output | meaning | action |\n|---------------|---------|--------|\n| command not found | not installed | install via `brew install aannoo/hcom/hcom`, the curl installer above, or `pip install hcom` |\n| `[~] claude` | tool exists, hooks not installed | `hcom hooks add` then restart |\n| `[✓] claude` | hooks installed | ready |\n| `[✗] claude` | tool not found | install the AI tool first |\n\n---\n\n## troubleshooting\n\n### \"hcom not working\"\n\n```bash\nhcom status          # check installation\nhcom hooks status    # check hooks specifically\nhcom relay status    # check cross-device relay\n```\n\nhooks missing? `hcom hooks add` then restart tool.\n\nstill broken?\n```bash\nhcom reset all && hcom hooks add\n# close all ai tool windows\nhcom claude          # fresh start\n```\n\n### \"messages not arriving\"\n\n| symptom | diagnosis | fix |\n|---------|-----------|-----|\n| agent not in `hcom list` | agent stopped or never bound | relaunch or wait for binding |\n| message sent but not delivered | check `hcom events --last 5` | verify @mention matches agent name/tag |\n| wrong agent receives message | @mention ambiguity | use `@tag-` prefix for reliable routing |\n| messages leaking between workflows | no thread isolation | always use `--thread` |\n\n### intent system\n\nagents follow these rules from their bootstrap:\n- `--intent request` -> agent always responds\n- `--intent inform` -> agent responds only if useful\n- `--intent ack` -> agent does not respond\n\n### sandbox / permission issues\n\n```bash\nexport HCOM_DIR=\"$PWD/.hcom\"     # project-local mode\nhcom hooks add                   # installs to project dir\n```\n\n---\n\n## workflow scripting\n\nplace scripts in `~/.hcom/scripts/` as `.sh` or `.py`. run with `hcom run <name> \"task\"`. see `references/script-template.md` for the full annotated template, or run `hcom run docs --scripts` inside an agent.\n\n### key rules\n\n- **never use `sleep`** — use `hcom events --wait` or `hcom listen`\n- **never hardcode agent names** — parse from `grep '^Names: '` in launch output\n- **always use `--thread`** — without it, messages leak across workflows\n- **always use `trap cleanup ERR INT TERM`** — orphan headless agents run indefinitely\n- **always use `hcom kill` for cleanup** (not `stop`) — kill also closes the terminal pane\n- **always forward `--name`** — hcom injects it, scripts must propagate it\n- **always use `--go`** on launch/kill — without it, scripts hang on confirmation prompt\n\n### agent topologies\n\n| topology | agents | pattern |\n|----------|--------|---------|\n| worker-reviewer | 2 | worker sends result, reviewer reads transcript, sends APPROVED/FIX |\n| pipeline | N sequential | each stage reads previous via `hcom transcript`, signals via thread |\n| ensemble | N+1 (judge) | N agents answer independently, judge reads all via `hcom events --sql` |\n| hub-spoke | 1+N | coordinator broadcasts to `@tag-`, workers report back |\n| reactive | N | `hcom events sub` triggers agent actions on file edits/status changes |\n\n---\n\n## files\n\n| what | location |\n|------|----------|\n| database | `~/.hcom/hcom.db` |\n| config | `~/.hcom/config.toml` |\n| logs | `~/.hcom/.tmp/logs/` |\n| user scripts | `~/.hcom/scripts/` |\n\nwith `HCOM_DIR` set, uses that path instead of `~/.hcom`.\n\n---\n\n## reference files\n\n| file | when to read |\n|------|-------------|\n| `references/patterns.md` | writing multi-agent scripts — 6 tested patterns with full code and real event JSON |\n| `references/cross-tool.md` | claude + codex + gemini + opencode collaboration details and per-tool quirks |\n| `references/gotchas.md` | debugging scripts — timing, message delivery, intent system, cleanup |\n| `references/script-template.md` | writing a new script from scratch — full template with commentary |\n| `references/scripts/` | 6 tested, working example scripts |\n\n---\n\n## more info\n\n```bash\nhcom --help              # all commands\nhcom <command> --help    # command details\n```\n\ngithub: https://github.com/aannoo/hcom","tags":["hcom","agent","messaging","aannoo","agent-skills","ai-agents","ai-tools","automation","claude","claude-code","claude-code-hooks","cli"],"capabilities":["skill","source-aannoo","skill-hcom-agent-messaging","topic-agent","topic-agent-skills","topic-ai-agents","topic-ai-tools","topic-automation","topic-claude","topic-claude-code","topic-claude-code-hooks","topic-cli","topic-codex","topic-coding-agent","topic-communication"],"categories":["hcom"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/aannoo/hcom/hcom-agent-messaging","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add aannoo/hcom","source_repo":"https://github.com/aannoo/hcom","install_from":"skills.sh"}},"qualityScore":"0.574","qualityRationale":"deterministic score 0.57 from registry signals: · indexed on github topic:agent-skills · 248 github stars · SKILL.md body (5,954 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T18:54:12.024Z","embedding":null,"createdAt":"2026-04-18T22:04:51.428Z","updatedAt":"2026-05-02T18:54:12.024Z","lastSeenAt":"2026-05-02T18:54:12.024Z","tsv":"'+1':659 '/.hcom':717 '/.hcom/.tmp/logs':704 '/.hcom/config.toml':702 '/.hcom/hcom.db':700 '/.hcom/scripts':521,707 '/aannoo/hcom':792 '/aannoo/hcom/releases/latest/download/hcom-installer.sh':79,294 '0.26.0':223 '1':279,675 '2':296,635 '3':308 '5':442 '6':730,773 'aannoo/hcom/hcom':330 'ack':492 'across':20,577 'action':320,691 'activ':316 'add':300,347,390,402,511 'agent':3,7,13,33,38,45,99,138,152,418,423,446,449,472,481,486,493,546,561,588,627,630,662,690,728 'ai':10,41,44,237,311,360,405 'also':600 'alway':467,482,570,579,591,605,615 'ambigu':453 'annot':536 'answer':663 'approved/fix':643 'argument':278 'arriv':414 'ask':147 'automat':189,218,224,228,232 'back':135,683 'bash':74,289,367,396,500,780 'bind':249,432 'bootstrap':478 'bound':427 'brew':328 'broadcast':678 'broken':395 'bug':126,132 'bundl':162 'chang':183,695 'check':370,375,381,438 'claud':82,104,214,220,339,350,354,409,741 'cleanup':582,596,760 'cli':222 'close':403,601 'code':11,42,143,215,735 'codex':87,106,227,230,742 'collabor':745 'command':174,205,284,321,784,787 'commentari':771 'communic':8,39 'config':701 'confirm':625 'connect':53,213 'context':163 'coordin':677 'cross':383 'cross-devic':382 'curl':75,290,332 'dashboard':92 'databas':60,699 'debug':753 'deliv':437 'deliveri':28,212,757 'detail':746,788 'detect':306 'devic':384 'diagnosi':416 'dir':503,515,710 'doc':542 'edit':118,171,185 'edits/status':694 'emul':199 'ensembl':657 'err':583 'event':187,440,554,670,687,738 'exampl':776 'exist':341 'export':501 'feedback':123 'file':117,170,184,693,696,719,720 'find':136 'first':259,262,288,362 'fix':417 'flag':208 'follow':473 'fork':127,191 'forward':606 'found':286,323,357 'fresh':410 'fssl':76,291 'full':204,535,734,768 'gemini':85,115,221,226,743 'github':789 'github.com':78,293,791 'github.com/aannoo/hcom':790 'github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh':77,292 'go':617 'goe':107 'grep':565 'handoff':165 'hang':623 'happen':257 'hardcod':560 'hcom':2,26,35,52,81,84,86,88,90,201,219,225,229,233,241,243,250,252,267,281,298,338,345,364,368,372,378,388,397,400,408,421,439,502,509,528,540,553,557,593,608,652,669,686,709,781,785 'hcom-agent-messag':1 'hcom-launch':266 'headless':587 'help':202,782,786 'histori':175 'hook':56,299,303,314,342,346,351,373,376,386,389,401,510 'hub':673 'hub-spok':672 'human':94 'id':142,256 'idl':108 'incl':216 'indefinit':590 'independ':664 'info':779 'inform':485 'inject':609 'insid':246,544 'instal':287,302,325,326,329,333,337,344,352,358,371,512 'instead':715 'int':584 'intent':470,479,484,491,758 'investig':130 'invok':274 'isol':51,466 'issu':499 'json':739 'judg':660,665 'key':547 'kill':193,594,599 'last':441 'launch':268,568 'launch/kill':619 'leak':461,576 'list':422 'listen':242,558 'local':507 'locat':698 'log':703 'manual':239 'match':445 'mean':319 'mention':444,452 'messag':4,14,64,102,155,260,412,433,451,460,575,756 'miss':387 'mode':508 'multi':6,32,37,727 'multi-ag':5,31,36,726 'must':612 'n':645,658,661,676,685 'name':562,566,607 'name/tag':447 'never':426,549,559 'new':764 'next':112 'notifi':180 'observ':166 'opencod':89,231,234,744 'orphan':586 'output':318,569 'pane':604 'pars':563 'path':714 'pattern':631,732 'per':749 'per-tool':748 'permiss':498 'pip':336 'pipelin':644 'place':518 'prefix':456 'previous':650 'project':506,514 'project-loc':505 'prompt':263,626 'propag':613 'pwd/.hcom':504 'py':525 'quirk':751 'r/f':253 'react':188 'reactiv':684 'read':640,649,666,723 'readi':353 'real':72,160,737 'real-tim':71,159 'receiv':450 'refer':718 'references/cross-tool.md':740 'references/gotchas.md':752 'references/patterns.md':724 'references/script-template.md':532,761 'references/scripts':772 'relaunch':428 'relay':379,385 'reliabl':458 'report':134,682 'request':480 'reset':398 'respond':483,487,496 'restart':309,349,392 'result':638 'resum':144,192 'review':119,634,639 'rout':459 'rule':475,548 'run':46,200,245,280,297,526,529,539,541,589 'sandbox':497 'scratch':767 'screen':173 'script':34,517,519,543,611,622,706,729,754,765,777 'see':531 'send':100,109,122,637,642 'sent':434 'separ':48 'sequenti':646 'session':248,255 'set':24,711 'setup':270 'sh':80,295,523 'share':59 'signal':654 'skill':276 'skill-hcom-agent-messaging' 'sleep':551 'source-aannoo' 'spawn':17,67,190 'specif':186,377 'spoke':674 'sql':671 'stage':648 'start':244,411 'status':182,282,317,369,374,380 'still':394 'stop':424,598 'sub':688 'subag':217 'subscrib':176 'suck':150 'support':210 'symptom':415 'syntax':206 'system':471,759 'tag':455,680 'task':113,530 'tell':97 'templat':537,769 'term':585 'termin':21,49,141,172,198,603 'test':731,774 'thread':465,469,572,656 'time':73,161,755 'tool':12,43,209,211,238,247,269,307,312,340,355,361,393,406,750 'topic-agent' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-tools' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-claude-code-hooks' 'topic-cli' 'topic-codex' 'topic-coding-agent' 'topic-communication' 'topolog':628,629 'transcript':169,251,641,653 'trap':581 'trigger':689 'troubleshoot':27,363 'tui':91 'use':22,454,468,490,550,552,571,580,592,616,712 'user':273,705 'verifi':443 'via':55,240,327,651,655,668 'wait':430,555 'watch':15,65,114 'window':407 'without':277,573,620 'work':139,366,775 'worker':633,636,681 'worker-review':632 'workflow':463,516,578 'write':30,725,762 'wrong':448","prices":[{"id":"efb3d5b4-a84f-4208-a060-149bdb5b4a8a","listingId":"9eea4bb0-b400-43d4-a5eb-5b1d24e97a17","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"aannoo","category":"hcom","install_from":"skills.sh"},"createdAt":"2026-04-18T22:04:51.428Z"}],"sources":[{"listingId":"9eea4bb0-b400-43d4-a5eb-5b1d24e97a17","source":"github","sourceId":"aannoo/hcom/hcom-agent-messaging","sourceUrl":"https://github.com/aannoo/hcom/tree/main/skills/hcom-agent-messaging","isPrimary":false,"firstSeenAt":"2026-04-18T22:04:51.428Z","lastSeenAt":"2026-05-02T18:54:12.024Z"}],"details":{"listingId":"9eea4bb0-b400-43d4-a5eb-5b1d24e97a17","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"aannoo","slug":"hcom-agent-messaging","github":{"repo":"aannoo/hcom","stars":248,"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"],"license":"mit","html_url":"https://github.com/aannoo/hcom","pushed_at":"2026-05-02T01:57:39Z","description":"Let AI agents message, watch, and spawn each other across terminals. Claude Code, Gemini CLI, Codex, OpenCode","skill_md_sha":"44b5e205072899bc8b3383edfda771bd84253737","skill_md_path":"skills/hcom-agent-messaging/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/aannoo/hcom/tree/main/skills/hcom-agent-messaging"},"layout":"multi","source":"github","category":"hcom","frontmatter":{"name":"hcom-agent-messaging","description":"Multi-agent communication for AI coding tools. Agents message, watch, and spawn each other across terminals. Use when setting up hcom, troubleshooting delivery, or writing multi-agent scripts."},"skills_sh_url":"https://skills.sh/aannoo/hcom/hcom-agent-messaging"},"updatedAt":"2026-05-02T18:54:12.024Z"}}