Skip to content

Commit 9e3004d

Browse files
aannooaannoo
committed
0.6.10: External stop enforcement, add Claude Code plugin
1 parent aa62831 commit 9e3004d

File tree

18 files changed

+394
-83
lines changed

18 files changed

+394
-83
lines changed

‎.claude-plugin/marketplace.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"name": "hcom",
3+
"owner": {
4+
"name": "aannoo",
5+
"url": "https://github.com/aannoo"
6+
},
7+
"description": "Multi-agent communication for Claude Code - launch multiple terminals with real-time messaging",
8+
"homepage": "https://github.com/aannoo/claude-hook-comms",
9+
"plugins": [
10+
{
11+
"name": "hcom",
12+
"source": "./plugin/hcom",
13+
"description": "CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks"
14+
}
15+
]
16+
}

‎README.md‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -69,19 +69,49 @@ hcom send "@backend scale up" # Message entire backend group
6969
```
7070

7171
### Subagent Communication
72-
Task tool subagents get their own identities and can talk to each other:
72+
73+
Task tool subagents get their own hcom identities and can message parent/each other:
74+
7375
```
7476
Parent: alice
75-
├── alice_reviewer_1 ──┐
76-
├── alice_explorer_1 ──┼── can message each other AND parent
77+
├── alice_explorer_1 ──┐
78+
├── alice_reviewer_1 ──┼── can message each other AND parent
7779
└── alice_planner_1 ──┘
7880
```
79-
Subagents stay alive after they finish their task (configurable timeout).
80-
Parents can communicate with subagents when they're in the background.
8181

82-
**Example:**
82+
Subagents stay alive after finishing their task (configurable timeout).
83+
Normal parent Claude can send messages to subagents who are running in the background.
84+
85+
To enable: tell claude to tell subagents use hcom
86+
87+
**Follow up questions**
88+
89+
Subagent investigates, reads 20 files, reports summary, normally dies.
90+
91+
You or parent claude have a follow-up question. Subagent already knows the answer from those 20 files - but it's dead.
92+
93+
With hcom: subagent stays alive, answers follow-ups in seconds instead of main claude or a new subagent re-investigating.
94+
95+
96+
**Guided Multi-Explore Comparison**
8397

84-
`"Use background task subagents to compare 3 different codebases, have each use hcom to send updates and you send follow-ups via hcom to steer and cross‑question them, then synthesize a final comparison"`
98+
Problem: 3 subagents explore 3 repos, each returns independent overview. Different focus areas, no shared baseline - comparison is shallow.
99+
100+
Solution: Parent guides all subagents in real-time with hcom. When one finds something, parent asks others to find the equivalent.
101+
102+
<details>
103+
<summary>example prompt</summary>
104+
105+
```
106+
Compare error handling across these 3 repos using background explore subagents.
107+
Have each hcom start and explore their repo's error handling.
108+
As they find patterns, have them immediately send each discovery via hcom to you.
109+
Use their findings to guide the others - when one reports a pattern,
110+
ask the others to look for the equivalent in their repo.
111+
Synthesize a comparison from the guided exploration.
112+
```
113+
114+
</details>
85115

86116
### External Tools
87117
Any process can join the conversation:

‎plugin/hcom/.claude-plugin/plugin.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "hcom",
3+
"version": "1.0.0",
4+
"description": "Multi-agent communication for Claude Code - real-time messaging between instances",
5+
"author": {
6+
"name": "aannoo",
7+
"url": "https://github.com/aannoo/claude-hook-comms"
8+
},
9+
"homepage": "https://github.com/aannoo/claude-hook-comms",
10+
"repository": "https://github.com/aannoo/claude-hook-comms",
11+
"license": "MIT",
12+
"keywords": [
13+
"hcom",
14+
"multi-agent",
15+
"communication",
16+
"messaging",
17+
"collaboration"
18+
]
19+
}

‎plugin/hcom/commands/hcom.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
description: HCOM reference and setup status
3+
allowed-tools: Bash
4+
disable-model-invocation: true
5+
---
6+
7+
# HCOM Status
8+
9+
## Installation Check
10+
!`command -v hcom >/dev/null 2>&1 && hcom -v || echo "NOT INSTALLED - restart Claude Code to auto-install"`
11+
12+
## Hooks Check
13+
!`grep -q '"HCOM"' ~/.claude/settings.json 2>/dev/null && echo "HOOKS: installed ✓" || echo "HOOKS: not installed - restart Claude Code"`
14+
15+
## Session Check
16+
!`echo "HCOM_SESSION_ID=$HCOM_SESSION_ID"`
17+
18+
## Current Instances
19+
Run `hcom list` to see active instances (requires active session)
20+
21+
---
22+
23+
# Setup Guide
24+
25+
Based on checks above:
26+
27+
**NOT_INSTALLED** → Restart Claude Code. Plugin will auto-install hcom.
28+
29+
**HOOKS: not installed** → Restart Claude Code. After install, hcom sets up hooks.
30+
31+
**SESSION: not active** → Run `hcom start` to enable in current session. If that fails, restart Claude Code.
32+
33+
**All green** → You're ready. Use `hcom` for TUI or `hcom send "msg"` to message.
34+
35+
## Quick Setup Flow
36+
1. Install plugin → restart Claude Code
37+
2. (hcom installs automatically)
38+
3. Restart Claude Code again (hooks now active)
39+
4. Run `hcom start` in your session
40+
41+
42+
If anything goes wrong or theres any issues, fresh start:
43+
```bash
44+
/plugin uninstall hcom@hcom
45+
hcom reset all && pip uninstall hcom
46+
pip install hcom && hcom -v
47+
# Then restart claude code and it should be working
48+
```
49+
50+
51+
---
52+
53+
# Reference
54+
55+
## README
56+
!`curl -fsSL https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/README.md 2>/dev/null || echo "Failed to fetch README from GitHub"`
57+
58+
---
59+
60+
# Troubleshooting
61+
62+
**"hcom: command not found"**
63+
- Restart Claude Code to trigger auto-install
64+
- Or manual: `pip install hcom`
65+
66+
**Hooks not working (no messages received)**
67+
- Check: `grep hcom ~/.claude/settings.json`
68+
- If missing, restart Claude Code after hcom install
69+
70+
**hcom start fails**
71+
- Restart Claude Code (hooks need to be active first)
72+
73+
**Messages not delivered**
74+
- Recipient must have run `hcom start`
75+
- Check `hcom list` for instance status
76+
77+
**Logs**
78+
- `~/.hcom/.tmp/logs/hooks.log`
79+
80+
---
81+
82+
# Uninstall
83+
84+
To completely remove hcom:
85+
86+
```bash
87+
/plugin uninstall hcom@hcom
88+
hcom reset all
89+
pip uninstall hcom
90+
```

‎plugin/hcom/hooks/hooks.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"description": "HCOM bootstrap",
3+
"hooks": {
4+
"SessionStart": [
5+
{
6+
"matcher": "",
7+
"hooks": [
8+
{
9+
"type": "command",
10+
"command": "command -v hcom >/dev/null 2>&1 || pip install -q hcom 2>/dev/null; if ! grep -q '\\${HCOM}' ~/.claude/settings.json 2>/dev/null; then VERSION=$(hcom -v 2>/dev/null); echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"HCOM plugin loaded ('\"$VERSION\"'). Run hcom -v to install hooks, then restart Claude Code.\"}}'; fi"
11+
}
12+
]
13+
}
14+
]
15+
}
16+
}

0 commit comments

Comments
 (0)