hcom 0.5.0__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of hcom might be problematic. Click here for more details.

hcom-0.6.0/MANIFEST.in ADDED
@@ -0,0 +1,17 @@
1
+ # Exclude development directories from source distribution
2
+ global-exclude __pycache__
3
+ global-exclude *.py[co]
4
+ prune test
5
+ prune tests
6
+ prune docs
7
+ prune dev
8
+ prune old
9
+ prune archive
10
+ prune prototypes
11
+ prune temp
12
+ prune plugin
13
+ prune scripts
14
+ prune reports
15
+ prune tui
16
+ prune todos
17
+ prune logs
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hcom
3
- Version: 0.5.0
4
- Summary: CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks
3
+ Version: 0.6.0
4
+ Summary: Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
5
5
  Author: aannoo
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://github.com/aannoo/claude-hook-comms
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
30
30
  [![PyPI - Version](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)
31
31
  [![PyPI - License](https://img.shields.io/pypi/l/hcom)](https://opensource.org/license/MIT) [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org) [![DeepWiki](https://img.shields.io/badge/DeepWiki-aannoo%2Fclaude--hook--comms-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/aannoo/claude-hook-comms)
32
32
 
33
- Launch multiple Claude Code terminals (or headless) that communicate together in real time via hooks.
33
+ Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
34
34
 
35
35
  ![Demo](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screencapture.gif)
36
36
 
@@ -48,7 +48,8 @@ pip install hcom # or: uv tool install hcom
48
48
 
49
49
  #### Use
50
50
  ```bash
51
- claude 'run hcom start'
51
+ hcom # UI - launch, monitor, message
52
+ claude 'run hcom start' # activate hcom for any claude code
52
53
  ```
53
54
 
54
55
 
@@ -61,29 +62,34 @@ claude 'run hcom start'
61
62
 
62
63
  | Command | Description
63
64
  |---------|-------------|
65
+ | `hcom` | Interactive dashboard |
64
66
  | `hcom <n>` | Launch `n` instances |
65
- | `hcom watch` | Live dashboard and messaging |
66
- | `hcom stop [alias\|all]` | Disable participation |
67
- | `hcom start [alias]` | Enable participation |
68
- | `hcom reset [logs\|hooks\|config]` | Safe Cleanup |
69
-
67
+ | `hcom start` | Enable participation |
68
+ | `hcom stop` | Disable participation |
70
69
 
71
70
 
72
71
  ## Examples
73
72
 
74
- #### Interactive subagents
73
+ #### communicate with task tool subagents
75
74
  ```bash
76
- # Claude Code subagents from .claude/agents
77
- HCOM_AGENT=planner,code-writer,reviewer hcom 1
75
+ claude 'use 3x task tool with task: say hi in hcom chat'
76
+ # Each subagent gets unique identity and can communicate with siblings
77
+ # Parent resumes after Task completes with full conversation history
78
78
  ```
79
79
 
80
- #### Persistent headless instances
80
+ #### persistent headless instances
81
81
  ```bash
82
- hcom 1 claude -p # default 30min timeout
83
- hcom watch # See what it's doing
82
+ hcom 1 claude -p # launch with default 30min timeout
83
+ hcom # See what it's doing from dashboard
84
84
  hcom stop # Let it die earlier than timeout
85
85
  ```
86
86
 
87
+ #### .claude/agents in interactive claude window
88
+ ```bash
89
+ HCOM_AGENT=code-writer hcom 1
90
+ HCOM_AGENT=reviewer hcom 1
91
+ ```
92
+
87
93
  #### @-mention: groups and direct
88
94
  ```bash
89
95
  HCOM_TAG=cooltag hcom 2
@@ -91,36 +97,36 @@ hcom send '@cooltag hi, you both are cool'
91
97
  hcom send '@john you are cooler'
92
98
  ```
93
99
 
94
- #### Toggle inside Claude Code
100
+ #### toggle inside claude code
95
101
  ```bash
96
102
  claude # Normal Claude Code
97
103
  'run hcom start' # Opt-in to receive messages
98
104
  'run hcom stop' # Opt-out, continue as normal claude code
99
105
  ```
100
106
 
107
+ ---
101
108
 
102
109
  <details>
103
110
  <summary><strong>All commands</strong></summary>
104
111
 
105
- ### `[ENV_VARS] hcom <COUNT> [claude <ARGS>]`
106
-
107
112
 
108
113
  ```bash
109
- Usage: [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
114
+ Usage: hcom # UI
115
+ [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
110
116
  hcom watch [--logs|--status|--wait [SEC]]
111
117
  hcom send "message"
112
- hcom stop [alias|all] [--force]
118
+ hcom stop [alias|all]
113
119
  hcom start [alias]
114
120
  hcom reset [logs|hooks|config]
115
121
 
116
122
  Launch Examples:
117
123
  hcom 3 Open 3 terminals with claude connected to hcom
118
- hcom 3 claude -p + Background/headless
124
+ hcom 3 claude -p + Headless
119
125
  HCOM_TAG=api hcom 3 claude -p + @-mention group tag
120
126
  claude 'run hcom start' claude code with prompt will also work
121
127
 
122
128
  Commands:
123
- watch Interactive messaging/status dashboard
129
+ watch messaging/status/launch UI (same as hcom no args)
124
130
  --logs Print all messages
125
131
  --status Print instance status JSON
126
132
  --wait [SEC] Wait and notify for new message
@@ -131,7 +137,6 @@ Commands:
131
137
  stop Stop current instance (from inside Claude)
132
138
  stop <alias> Stop specific instance
133
139
  stop all Stop all instances
134
- --force Emergency stop (denies Bash tool)
135
140
 
136
141
  start Start current instance (from inside Claude)
137
142
  start <alias> Start specific instance
@@ -142,20 +147,32 @@ Commands:
142
147
  reset config Clear + backup config.env
143
148
 
144
149
  Environment Variables:
145
- HCOM_TAG=name Group tag (creates name-* instances)
146
- HCOM_AGENT=type Agent type (comma-separated for multiple)
147
- HCOM_TERMINAL=mode Terminal: new|here|print|"custom {script}"
148
- HCOM_PROMPT=text "Say hi in hcom chat" (default)
149
- HCOM_HINTS=text Text appended to all messages received by instance
150
- HCOM_TIMEOUT=secs Time until disconnected from hcom chat (default 1800s / 30mins)
150
+ HCOM_TAG=name Group tag (creates name-* instances)
151
+ HCOM_AGENT=type Agent type (comma-separated for multiple)
152
+ HCOM_TERMINAL=mode Terminal: new|here|print|"custom {script}"
153
+ HCOM_HINTS=text Text appended to all messages received by instance
154
+ HCOM_TIMEOUT=secs Time until disconnected from hcom chat (default 1800s / 30mins)
155
+ HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
156
+ HCOM_CLAUDE_ARGS=args Claude CLI defaults (e.g., '-p --model opus "hello!"')
151
157
 
152
- ANTHROPIC_MODEL=opus # Passed through to Claude Code
158
+ ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
153
159
 
154
160
  Persist Env Vars in `~/.hcom/config.env`
155
-
156
161
  ```
162
+
163
+ ---
164
+
165
+ ### Requirements
166
+
167
+ - Python 3.10+
168
+ - Claude Code
169
+
170
+
171
+
157
172
  </details>
158
173
 
174
+ ---
175
+
159
176
  <details>
160
177
  <summary><strong> Terminal Options</strong></summary>
161
178
 
@@ -170,7 +187,7 @@ Environment Variables:
170
187
 
171
188
  - `HCOM_TERMINAL=new` - New terminal windows (default)
172
189
  - `HCOM_TERMINAL=here` - Current terminal window
173
- - `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal (**iTerm2**)
190
+ - `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal
174
191
 
175
192
 
176
193
  ### Custom Terminal
@@ -242,16 +259,11 @@ HCOM_TERMINAL="/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bas
242
259
  `hcom 2`
243
260
  ```
244
261
 
245
- ---
246
-
247
262
  </details>
248
263
 
249
- ## Requirements
250
-
251
- - Python 3.10+
252
- - Claude Code
264
+ ---
253
265
 
254
- ## License
266
+ ### License
255
267
 
256
268
  MIT
257
269
 
@@ -3,7 +3,7 @@
3
3
  [![PyPI - Version](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)
4
4
  [![PyPI - License](https://img.shields.io/pypi/l/hcom)](https://opensource.org/license/MIT) [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org) [![DeepWiki](https://img.shields.io/badge/DeepWiki-aannoo%2Fclaude--hook--comms-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/aannoo/claude-hook-comms)
5
5
 
6
- Launch multiple Claude Code terminals (or headless) that communicate together in real time via hooks.
6
+ Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
7
7
 
8
8
  ![Demo](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screencapture.gif)
9
9
 
@@ -21,7 +21,8 @@ pip install hcom # or: uv tool install hcom
21
21
 
22
22
  #### Use
23
23
  ```bash
24
- claude 'run hcom start'
24
+ hcom # UI - launch, monitor, message
25
+ claude 'run hcom start' # activate hcom for any claude code
25
26
  ```
26
27
 
27
28
 
@@ -34,29 +35,34 @@ claude 'run hcom start'
34
35
 
35
36
  | Command | Description
36
37
  |---------|-------------|
38
+ | `hcom` | Interactive dashboard |
37
39
  | `hcom <n>` | Launch `n` instances |
38
- | `hcom watch` | Live dashboard and messaging |
39
- | `hcom stop [alias\|all]` | Disable participation |
40
- | `hcom start [alias]` | Enable participation |
41
- | `hcom reset [logs\|hooks\|config]` | Safe Cleanup |
42
-
40
+ | `hcom start` | Enable participation |
41
+ | `hcom stop` | Disable participation |
43
42
 
44
43
 
45
44
  ## Examples
46
45
 
47
- #### Interactive subagents
46
+ #### communicate with task tool subagents
48
47
  ```bash
49
- # Claude Code subagents from .claude/agents
50
- HCOM_AGENT=planner,code-writer,reviewer hcom 1
48
+ claude 'use 3x task tool with task: say hi in hcom chat'
49
+ # Each subagent gets unique identity and can communicate with siblings
50
+ # Parent resumes after Task completes with full conversation history
51
51
  ```
52
52
 
53
- #### Persistent headless instances
53
+ #### persistent headless instances
54
54
  ```bash
55
- hcom 1 claude -p # default 30min timeout
56
- hcom watch # See what it's doing
55
+ hcom 1 claude -p # launch with default 30min timeout
56
+ hcom # See what it's doing from dashboard
57
57
  hcom stop # Let it die earlier than timeout
58
58
  ```
59
59
 
60
+ #### .claude/agents in interactive claude window
61
+ ```bash
62
+ HCOM_AGENT=code-writer hcom 1
63
+ HCOM_AGENT=reviewer hcom 1
64
+ ```
65
+
60
66
  #### @-mention: groups and direct
61
67
  ```bash
62
68
  HCOM_TAG=cooltag hcom 2
@@ -64,36 +70,36 @@ hcom send '@cooltag hi, you both are cool'
64
70
  hcom send '@john you are cooler'
65
71
  ```
66
72
 
67
- #### Toggle inside Claude Code
73
+ #### toggle inside claude code
68
74
  ```bash
69
75
  claude # Normal Claude Code
70
76
  'run hcom start' # Opt-in to receive messages
71
77
  'run hcom stop' # Opt-out, continue as normal claude code
72
78
  ```
73
79
 
80
+ ---
74
81
 
75
82
  <details>
76
83
  <summary><strong>All commands</strong></summary>
77
84
 
78
- ### `[ENV_VARS] hcom <COUNT> [claude <ARGS>]`
79
-
80
85
 
81
86
  ```bash
82
- Usage: [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
87
+ Usage: hcom # UI
88
+ [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
83
89
  hcom watch [--logs|--status|--wait [SEC]]
84
90
  hcom send "message"
85
- hcom stop [alias|all] [--force]
91
+ hcom stop [alias|all]
86
92
  hcom start [alias]
87
93
  hcom reset [logs|hooks|config]
88
94
 
89
95
  Launch Examples:
90
96
  hcom 3 Open 3 terminals with claude connected to hcom
91
- hcom 3 claude -p + Background/headless
97
+ hcom 3 claude -p + Headless
92
98
  HCOM_TAG=api hcom 3 claude -p + @-mention group tag
93
99
  claude 'run hcom start' claude code with prompt will also work
94
100
 
95
101
  Commands:
96
- watch Interactive messaging/status dashboard
102
+ watch messaging/status/launch UI (same as hcom no args)
97
103
  --logs Print all messages
98
104
  --status Print instance status JSON
99
105
  --wait [SEC] Wait and notify for new message
@@ -104,7 +110,6 @@ Commands:
104
110
  stop Stop current instance (from inside Claude)
105
111
  stop <alias> Stop specific instance
106
112
  stop all Stop all instances
107
- --force Emergency stop (denies Bash tool)
108
113
 
109
114
  start Start current instance (from inside Claude)
110
115
  start <alias> Start specific instance
@@ -115,20 +120,32 @@ Commands:
115
120
  reset config Clear + backup config.env
116
121
 
117
122
  Environment Variables:
118
- HCOM_TAG=name Group tag (creates name-* instances)
119
- HCOM_AGENT=type Agent type (comma-separated for multiple)
120
- HCOM_TERMINAL=mode Terminal: new|here|print|"custom {script}"
121
- HCOM_PROMPT=text "Say hi in hcom chat" (default)
122
- HCOM_HINTS=text Text appended to all messages received by instance
123
- HCOM_TIMEOUT=secs Time until disconnected from hcom chat (default 1800s / 30mins)
123
+ HCOM_TAG=name Group tag (creates name-* instances)
124
+ HCOM_AGENT=type Agent type (comma-separated for multiple)
125
+ HCOM_TERMINAL=mode Terminal: new|here|print|"custom {script}"
126
+ HCOM_HINTS=text Text appended to all messages received by instance
127
+ HCOM_TIMEOUT=secs Time until disconnected from hcom chat (default 1800s / 30mins)
128
+ HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
129
+ HCOM_CLAUDE_ARGS=args Claude CLI defaults (e.g., '-p --model opus "hello!"')
124
130
 
125
- ANTHROPIC_MODEL=opus # Passed through to Claude Code
131
+ ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
126
132
 
127
133
  Persist Env Vars in `~/.hcom/config.env`
128
-
129
134
  ```
135
+
136
+ ---
137
+
138
+ ### Requirements
139
+
140
+ - Python 3.10+
141
+ - Claude Code
142
+
143
+
144
+
130
145
  </details>
131
146
 
147
+ ---
148
+
132
149
  <details>
133
150
  <summary><strong> Terminal Options</strong></summary>
134
151
 
@@ -143,7 +160,7 @@ Environment Variables:
143
160
 
144
161
  - `HCOM_TERMINAL=new` - New terminal windows (default)
145
162
  - `HCOM_TERMINAL=here` - Current terminal window
146
- - `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal (**iTerm2**)
163
+ - `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal
147
164
 
148
165
 
149
166
  ### Custom Terminal
@@ -215,16 +232,11 @@ HCOM_TERMINAL="/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bas
215
232
  `hcom 2`
216
233
  ```
217
234
 
218
- ---
219
-
220
235
  </details>
221
236
 
222
- ## Requirements
223
-
224
- - Python 3.10+
225
- - Claude Code
237
+ ---
226
238
 
227
- ## License
239
+ ### License
228
240
 
229
241
  MIT
230
242
 
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "hcom"
7
- version = "0.5.0"
8
- description = "CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks"
7
+ dynamic = ["version"]
8
+ description = "Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
11
11
  license = "MIT"
@@ -37,7 +37,10 @@ Issues = "https://github.com/aannoo/claude-hook-comms/issues"
37
37
  Documentation = "https://github.com/aannoo/claude-hook-comms#readme"
38
38
 
39
39
  [tool.setuptools]
40
- package-dir = {"" = "src"}
40
+ packages = ["hcom"]
41
41
 
42
- [tool.setuptools.packages.find]
43
- where = ["src"]
42
+ [tool.setuptools.package-dir]
43
+ "" = "src"
44
+
45
+ [tool.setuptools.dynamic]
46
+ version = {attr = "hcom.shared.__version__"}
@@ -0,0 +1,3 @@
1
+ from .shared import __version__
2
+
3
+ __all__ = ["__version__"]
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())