hcom 0.4.2.post3__tar.gz → 0.6.0__tar.gz

hcom-0.6.0/MANIFEST.in

@@ -0,0 +1,17 @@
+# Exclude development directories from source distribution
+global-exclude __pycache__
+global-exclude *.py[co]
+prune test
+prune tests
+prune docs
+prune dev
+prune old
+prune archive
+prune prototypes
+prune temp
+prune plugin
+prune scripts
+prune reports
+prune tui
+prune todos
+prune logs

hcom-0.6.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: hcom
+Version: 0.6.0
+Summary: Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
+Author: aannoo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aannoo/claude-hook-comms
+Project-URL: Repository, https://github.com/aannoo/claude-hook-comms
+Project-URL: Issues, https://github.com/aannoo/claude-hook-comms/issues
+Project-URL: Documentation, https://github.com/aannoo/claude-hook-comms#readme
+Keywords: claude,claude-code,hooks,agents,cli,multi-agent,orchestration,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hcom — Claude Hook Comms
+
+[![PyPI - Version](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)
+ [![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)
+
+Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
+
+![Demo](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screencapture.gif)
+
+## Start
+
+#### Run without installing
+```bash
+uvx hcom 2
+```
+
+#### Install
+```bash
+pip install hcom   # or: uv tool install hcom
+```
+
+#### Use
+```bash
+hcom                     # UI - launch, monitor, message
+claude 'run hcom start'  # activate hcom for any claude code
+```
+
+
+## What it does
+
+`hcom` adds hooks then launches terminals with Claude Code that remain active, waiting to respond to messages. Normal `claude` remains unaffected by hcom, but can opt-in/out with `hcom start`/`hcom stop`. Safely remove hcom hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
+
+
+## Commands
+
+| Command | Description
+|---------|-------------|
+| `hcom` | Interactive dashboard |
+| `hcom <n>` | Launch `n` instances |
+| `hcom start` | Enable participation |
+| `hcom stop` | Disable participation |
+
+
+## Examples
+
+#### communicate with task tool subagents
+```bash
+claude 'use 3x task tool with task: say hi in hcom chat'
+# Each subagent gets unique identity and can communicate with siblings
+# Parent resumes after Task completes with full conversation history
+```
+
+#### persistent headless instances
+```bash
+hcom 1 claude -p    # launch with default 30min timeout
+hcom                # See what it's doing from dashboard
+hcom stop           # Let it die earlier than timeout
+```
+
+#### .claude/agents in interactive claude window
+```bash
+HCOM_AGENT=code-writer hcom 1
+HCOM_AGENT=reviewer hcom 1
+```
+
+#### @-mention: groups and direct
+```bash
+HCOM_TAG=cooltag hcom 2
+hcom send '@cooltag hi, you both are cool'
+hcom send '@john you are cooler'
+```
+
+#### toggle inside claude code
+```bash
+claude              # Normal Claude Code
+'run hcom start'    # Opt-in to receive messages
+'run hcom stop'     # Opt-out, continue as normal claude code
+```
+
+---
+
+<details>
+<summary><strong>All commands</strong></summary>
+
+
+```bash
+Usage: hcom   # UI
+       [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+       hcom watch [--logs|--status|--wait [SEC]]
+       hcom send "message"
+       hcom stop [alias|all]
+       hcom start [alias]
+       hcom reset [logs|hooks|config]
+
+Launch Examples:
+  hcom 3             Open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                            + Headless
+  HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
+  claude 'run hcom start'    claude code with prompt will also work
+
+Commands:
+  watch              messaging/status/launch UI (same as hcom no args)
+    --logs           Print all messages
+    --status         Print instance status JSON
+    --wait [SEC]     Wait and notify for new message
+
+  send "msg"         Send message to all instances
+  send "@alias msg"  Send to specific instance/group
+
+  stop               Stop current instance (from inside Claude)
+  stop <alias>       Stop specific instance
+  stop all           Stop all instances
+
+  start              Start current instance (from inside Claude)
+  start <alias>      Start specific instance
+
+  reset              Stop all + archive logs + remove hooks + clear config
+  reset logs         Clear + archive conversation log
+  reset hooks        Safely remove hcom hooks from claude settings.json
+  reset config       Clear + backup config.env
+
+Environment Variables:
+  HCOM_TAG=name              Group tag (creates name-* instances)
+  HCOM_AGENT=type            Agent type (comma-separated for multiple)
+  HCOM_TERMINAL=mode         Terminal: new|here|print|"custom {script}"
+  HCOM_HINTS=text            Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs          Time until disconnected from hcom chat (default 1800s / 30mins)
+  HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
+  HCOM_CLAUDE_ARGS=args      Claude CLI defaults (e.g., '-p --model opus "hello!"')
+
+  ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
+
+  Persist Env Vars in `~/.hcom/config.env`
+```
+
+---
+
+### Requirements
+
+- Python 3.10+
+- Claude Code
+ 
+  
+
+</details>
+
+---
+
+<details>
+<summary><strong> Terminal Options</strong></summary>
+
+### Default Terminals
+
+- **macOS**: Terminal.app
+- **Linux**: gnome-terminal, konsole, or xterm
+- **Windows (native) & WSL**: Windows Terminal / Git Bash
+- **Android**: Termux
+
+### Terminal Mode
+
+- `HCOM_TERMINAL=new` - New terminal windows (default)
+- `HCOM_TERMINAL=here` - Current terminal window
+- `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal
+
+
+### Custom Terminal
+
+Your custom command just needs to:
+1. Accept `{script}` as a placeholder that will be replaced with a script path
+2. Execute that script with bash
+
+### Custom Terminal Examples
+
+##### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)
+```bash
+HCOM_TERMINAL="ttab {script}"
+```
+
+##### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)
+```bash
+HCOM_TERMINAL="wttab {script}"
+```
+
+##### More
+```bash
+# Wave Terminal Mac/Linux/Windows. From within Wave Terminal:
+HCOM_TERMINAL="wsh run -- bash {script}"
+
+# Alacritty macOS:
+HCOM_TERMINAL="open -n -a Alacritty.app --args -e bash {script}"
+
+# Alacritty Linux:
+HCOM_TERMINAL="alacritty -e bash {script}"
+
+# Kitty macOS:
+HCOM_TERMINAL="open -n -a kitty.app --args {script}"
+
+# Kitty Linux
+HCOM_TERMINAL="kitty {script}"
+
+# tmux with split panes and 3 claude instances in hcom chat
+HCOM_TERMINAL="tmux split-window -h {script}" hcom 3
+
+# WezTerm Linux/Windows
+HCOM_TERMINAL="wezterm start -- bash {script}"
+
+# Tabs from within WezTerm
+HCOM_TERMINAL="wezterm cli spawn -- bash {script}"
+
+# WezTerm macOS:
+HCOM_TERMINAL="open -n -a WezTerm.app --args start -- bash {script}"
+
+# Tabs from within WezTerm macOS
+HCOM_TERMINAL="/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bash {script}"
+```
+
+#### Android (Termux)
+
+```bash
+#1. Install:
+    Termux from F-Droid (not Google Play)
+#2. Setup:
+   pkg install python nodejs
+   npm install -g @anthropic-ai/claude-cli
+   pip install hcom
+#3. Enable:
+   echo "allow-external-apps=true" >> ~/.termux/termux.properties
+   termux-reload-settings
+#4. Enable: 
+    "Display over other apps" permission for visible terminals
+#5. Run: 
+    `hcom 2`
+```
+
+</details>
+
+---
+
+### License
+
+MIT
+

hcom-0.6.0/README.md

@@ -0,0 +1,242 @@
+# hcom — Claude Hook Comms
+
+[![PyPI - Version](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)
+ [![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)
+
+Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
+
+![Demo](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screencapture.gif)
+
+## Start
+
+#### Run without installing
+```bash
+uvx hcom 2
+```
+
+#### Install
+```bash
+pip install hcom   # or: uv tool install hcom
+```
+
+#### Use
+```bash
+hcom                     # UI - launch, monitor, message
+claude 'run hcom start'  # activate hcom for any claude code
+```
+
+
+## What it does
+
+`hcom` adds hooks then launches terminals with Claude Code that remain active, waiting to respond to messages. Normal `claude` remains unaffected by hcom, but can opt-in/out with `hcom start`/`hcom stop`. Safely remove hcom hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
+
+
+## Commands
+
+| Command | Description
+|---------|-------------|
+| `hcom` | Interactive dashboard |
+| `hcom <n>` | Launch `n` instances |
+| `hcom start` | Enable participation |
+| `hcom stop` | Disable participation |
+
+
+## Examples
+
+#### communicate with task tool subagents
+```bash
+claude 'use 3x task tool with task: say hi in hcom chat'
+# Each subagent gets unique identity and can communicate with siblings
+# Parent resumes after Task completes with full conversation history
+```
+
+#### persistent headless instances
+```bash
+hcom 1 claude -p    # launch with default 30min timeout
+hcom                # See what it's doing from dashboard
+hcom stop           # Let it die earlier than timeout
+```
+
+#### .claude/agents in interactive claude window
+```bash
+HCOM_AGENT=code-writer hcom 1
+HCOM_AGENT=reviewer hcom 1
+```
+
+#### @-mention: groups and direct
+```bash
+HCOM_TAG=cooltag hcom 2
+hcom send '@cooltag hi, you both are cool'
+hcom send '@john you are cooler'
+```
+
+#### toggle inside claude code
+```bash
+claude              # Normal Claude Code
+'run hcom start'    # Opt-in to receive messages
+'run hcom stop'     # Opt-out, continue as normal claude code
+```
+
+---
+
+<details>
+<summary><strong>All commands</strong></summary>
+
+
+```bash
+Usage: hcom   # UI
+       [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+       hcom watch [--logs|--status|--wait [SEC]]
+       hcom send "message"
+       hcom stop [alias|all]
+       hcom start [alias]
+       hcom reset [logs|hooks|config]
+
+Launch Examples:
+  hcom 3             Open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                            + Headless
+  HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
+  claude 'run hcom start'    claude code with prompt will also work
+
+Commands:
+  watch              messaging/status/launch UI (same as hcom no args)
+    --logs           Print all messages
+    --status         Print instance status JSON
+    --wait [SEC]     Wait and notify for new message
+
+  send "msg"         Send message to all instances
+  send "@alias msg"  Send to specific instance/group
+
+  stop               Stop current instance (from inside Claude)
+  stop <alias>       Stop specific instance
+  stop all           Stop all instances
+
+  start              Start current instance (from inside Claude)
+  start <alias>      Start specific instance
+
+  reset              Stop all + archive logs + remove hooks + clear config
+  reset logs         Clear + archive conversation log
+  reset hooks        Safely remove hcom hooks from claude settings.json
+  reset config       Clear + backup config.env
+
+Environment Variables:
+  HCOM_TAG=name              Group tag (creates name-* instances)
+  HCOM_AGENT=type            Agent type (comma-separated for multiple)
+  HCOM_TERMINAL=mode         Terminal: new|here|print|"custom {script}"
+  HCOM_HINTS=text            Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs          Time until disconnected from hcom chat (default 1800s / 30mins)
+  HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
+  HCOM_CLAUDE_ARGS=args      Claude CLI defaults (e.g., '-p --model opus "hello!"')
+
+  ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
+
+  Persist Env Vars in `~/.hcom/config.env`
+```
+
+---
+
+### Requirements
+
+- Python 3.10+
+- Claude Code
+ 
+  
+
+</details>
+
+---
+
+<details>
+<summary><strong> Terminal Options</strong></summary>
+
+### Default Terminals
+
+- **macOS**: Terminal.app
+- **Linux**: gnome-terminal, konsole, or xterm
+- **Windows (native) & WSL**: Windows Terminal / Git Bash
+- **Android**: Termux
+
+### Terminal Mode
+
+- `HCOM_TERMINAL=new` - New terminal windows (default)
+- `HCOM_TERMINAL=here` - Current terminal window
+- `HCOM_TERMINAL="open -a iTerm {script}"` - Custom terminal
+
+
+### Custom Terminal
+
+Your custom command just needs to:
+1. Accept `{script}` as a placeholder that will be replaced with a script path
+2. Execute that script with bash
+
+### Custom Terminal Examples
+
+##### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)
+```bash
+HCOM_TERMINAL="ttab {script}"
+```
+
+##### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)
+```bash
+HCOM_TERMINAL="wttab {script}"
+```
+
+##### More
+```bash
+# Wave Terminal Mac/Linux/Windows. From within Wave Terminal:
+HCOM_TERMINAL="wsh run -- bash {script}"
+
+# Alacritty macOS:
+HCOM_TERMINAL="open -n -a Alacritty.app --args -e bash {script}"
+
+# Alacritty Linux:
+HCOM_TERMINAL="alacritty -e bash {script}"
+
+# Kitty macOS:
+HCOM_TERMINAL="open -n -a kitty.app --args {script}"
+
+# Kitty Linux
+HCOM_TERMINAL="kitty {script}"
+
+# tmux with split panes and 3 claude instances in hcom chat
+HCOM_TERMINAL="tmux split-window -h {script}" hcom 3
+
+# WezTerm Linux/Windows
+HCOM_TERMINAL="wezterm start -- bash {script}"
+
+# Tabs from within WezTerm
+HCOM_TERMINAL="wezterm cli spawn -- bash {script}"
+
+# WezTerm macOS:
+HCOM_TERMINAL="open -n -a WezTerm.app --args start -- bash {script}"
+
+# Tabs from within WezTerm macOS
+HCOM_TERMINAL="/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bash {script}"
+```
+
+#### Android (Termux)
+
+```bash
+#1. Install:
+    Termux from F-Droid (not Google Play)
+#2. Setup:
+   pkg install python nodejs
+   npm install -g @anthropic-ai/claude-cli
+   pip install hcom
+#3. Enable:
+   echo "allow-external-apps=true" >> ~/.termux/termux.properties
+   termux-reload-settings
+#4. Enable: 
+    "Display over other apps" permission for visible terminals
+#5. Run: 
+    `hcom 2`
+```
+
+</details>
+
+---
+
+### License
+
+MIT
+

{hcom-0.4.2.post3 → hcom-0.6.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hcom"
-version = "0.4.2.post3"
-description = "CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks"
+dynamic = ["version"]
+description = "Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -37,7 +37,10 @@ Issues = "https://github.com/aannoo/claude-hook-comms/issues"
 Documentation = "https://github.com/aannoo/claude-hook-comms#readme"
 
 [tool.setuptools]
-package-dir = {"" = "src"}
+packages = ["hcom"]
 
-[tool.setuptools.packages.find]
-where = ["src"]
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.dynamic]
+version = {attr = "hcom.shared.__version__"}

hcom-0.6.0/src/hcom/__init__.py

@@ -0,0 +1,3 @@
+from .shared import __version__
+
+__all__ = ["__version__"]

hcom-0.6.0/src/hcom/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())