hcom 0.1.0__tar.gz

hcom-0.1.0/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: hcom
+Version: 0.1.0
+Summary: Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using hooks
+Author-email: aannoo <your@email.com>
+License: 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
+Keywords: claude,claude-code,hooks,agents,cli,multi-agent-orchestration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Communications
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+
+# Claude Code Hook Comms
+
+Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
+
+## 🦆 What It Does
+
+Creates a group chat where you and multiple interactive Claude Code subagents can communicate with each other across different folders on your computer. Works on Mac, Linux, and Windows with zero dependencies.
+
+![Claude Hook Comms Example](screenshot.jpg)
+
+## 🦷 Key Features
+
+- **New Window** - Claude subagents open in new terminals
+- **Multi-Agent Communication** - Claude instances talk to each other across projects
+- **@Mention Targeting** - Send messages to specific subagents or teams
+- **Live Dashboard** - Real-time monitoring of all instances
+- **Zero Dependencies** - Pure Python stdlib, works everywhere
+
+## 🎪 Quick Start
+
+### Download
+```bash
+curl -sL https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py | sudo tee /usr/local/bin/hcom > /dev/null && sudo chmod +x /usr/local/bin/hcom
+```
+
+<details>
+<summary><strong>🦑 Windows</strong></summary>
+
+```powershell
+# Download Python file
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py" -OutFile "hcom.py"
+
+# Run python file directly
+python path/to/hcom.py open 2
+```
+</details>
+
+### Usage
+```bash
+# 1. Launch 3 Claude instances connected to group chat
+hcom open 3
+
+# 2. View/send messages in dashboard
+hcom watch
+```
+
+
+
+### Launch Claude Code Agents
+```bash
+# Launch researcher and code-writer from your .claude/agents
+hcom open researcher code-writer
+
+# Launch backend-coder frontend-coder orchestrator tester from your .claude/agents
+hcom open backend-coder frontend-coder orchestrator tester
+```
+
+### Launch Headless Mode
+```bash
+# Launch researcher and code-writer from your .claude/agents and work in background
+hcom open researcher code-writer --claude-args "-p"
+
+# Launch reviewer in headless mode with a prompt
+hcom open --claude-args "-p 'review git code changes when you get notified'"
+```
+
+### Launch with Options
+```bash
+# Launch researcher and code-writer from your .claude/agents and work in background
+hcom open researcher code-writer --prefix 'greenteam'
+hcom send '@greenteam get to work on green stuff'
+
+# Launch 2 claude code instances and 2 of your agents
+hcom open 2 backend-coder frontend-coder
+```
+
+
+## 🦐 Requirements
+
+- Python 3.6+
+- [Claude Code](https://claude.ai/code)
+
+
+## 🥨 Commands
+
+### Commands
+| Command | Description |
+|---------|-------------|
+| `hcom open [n]` | Launch n Claude instances (or named agents) |
+| `hcom watch` | View conversation/status dashboard |
+| `hcom clear` | Clear and archive conversation |
+| `hcom cleanup` | Remove HCOM hooks from current directory |
+
+### Automation Commands
+| Command | Description |
+|---------|-------------|
+| `hcom send 'message'` | Send message |
+| `hcom watch --logs` | View message history (non-interactive) |
+| `hcom watch --status` | Show instance status (non-interactive) |
+| `hcom watch --wait[=seconds]` | Wait for new messages (automation) |
+
+---
+
+<details>
+<summary><strong>🦖 Configuration</strong></summary>
+
+### Configuration
+
+Settings can be changed two ways:
+
+```bash
+# Method 1: Environment variable (termporary per-command/instance)
+HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-but-not-great-with-updates
+
+# Method 2: Config file (affects all instances)
+# Edit ~/.hcom/config.json
+```
+
+### All Settings
+
+### Config File Location
+
+`~/.hcom/config.json`
+
+| Setting | Default | Environment Variable | Description |
+|---------|---------|---------------------|-------------|
+| `wait_timeout` | 600 | `HCOM_WAIT_TIMEOUT` | How long instances wait for messages (seconds) |
+| `max_message_size` | 4096 | `HCOM_MAX_MESSAGE_SIZE` | Maximum message length |
+| `max_messages_per_delivery` | 20 | `HCOM_MAX_MESSAGES_PER_DELIVERY` | Messages delivered per batch |
+| `sender_name` | "bigboss" | `HCOM_SENDER_NAME` | Your name in chat |
+| `sender_emoji` | "🐳" | `HCOM_SENDER_EMOJI` | Your emoji icon |
+| `initial_prompt` | "Say hi" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |
+| `first_use_text` | "Essential, concise messages only. Say hi in hcom chat" | `HCOM_FIRST_USE_TEXT` | Welcome message for instances |
+| `terminal_mode` | "new_window" | `HCOM_TERMINAL_MODE` | How to launch terminals ("new_window", "same_terminal", "show_commands") |
+| `terminal_command` | null | `HCOM_TERMINAL_COMMAND` | Custom terminal command (see Terminal Integration) |
+| `cli_hints` | "" | `HCOM_CLI_HINTS` | Extra text added to CLI outputs |
+| `instance_hints` | "" | `HCOM_INSTANCE_HINTS` | Extra text added to instance messages |
+| `env_overrides` | {} | - | Additional environment variables for Claude |
+
+### Examples
+
+```bash
+# Change your name for one command
+HCOM_SENDER_NAME="reviewer" hcom send "LGTM!"
+
+# Make instances wait 30 minutes instead of 10
+HCOM_WAIT_TIMEOUT=1800 hcom open 3
+
+# Custom welcome message
+HCOM_FIRST_USE_TEXT="Debug session for issue #123" hcom open 2
+
+# Bigger messages
+HCOM_MAX_MESSAGE_SIZE=8192 hcom send "$(cat long_report.txt)"
+```
+
+### Status Indicators
+- ◉ **thinking** (cyan) - Processing input
+- ▷ **responding** (green) - Generating text response  
+- ▶ **executing** (green) - Running tools
+- ◉ **waiting** (blue) - Waiting for messages
+- ■ **blocked** (yellow) - Permission blocked
+- ○ **inactive** (red) - Timed out/dead
+
+</details>
+
+<details>
+<summary><strong>🎲 How It Works</strong></summary>
+
+### Hooks!
+
+hcom adds hooks to your project directory's `.claude/settings.local.json`:
+
+1. **Sending**: Claude writes messages with `echo "HCOM_SEND:message"` - captured by PostToolUse hook
+2. **Receiving**: Other Claudes get notified via Stop hook
+3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages
+
+- **Identity**: Each instance gets a unique name based on conversation UUID (e.g., "hovoa7")
+- **Persistence**: Names persist across `claude --resume` maintaining conversation context
+- **Status Detection**: Notification hook tracks permission requests and activity
+
+### Architecture
+- **Single conversation** - All instances share one global conversation
+- **Opt-in participation** - Only instances launched with `hcom open` join the chat
+- **@-mention filtering** - Target messages to specific instances or teams
+
+### File Structure
+```
+~/.hcom/                             
+├── hcom.log       # Conversation log
+├── hcom.json      # Instance tracking
+└── config.json    # Configuration
+
+your-project/  
+└── .claude/
+    └── settings.local.json  # hcom hooks configuration
+```
+
+</details>
+
+
+<details>
+<summary><strong>🧈 Launching Claude Code</strong></summary>
+
+### Launching Claude Code
+
+Use `hcom open` to automatically launch Claude instances with proper setup:
+
+```bash
+# Launch 3 generic instances
+hcom open 3
+
+# Launch with custom terminal mode
+hcom open 2  # Uses terminal_mode from config
+
+# Launch named agents
+hcom open writer researcher
+```
+
+Configure terminal behavior in `~/.hcom/config.json`:
+- `"terminal_mode": "new_window"` - Opens new terminal windows (default)
+- `"terminal_mode": "same_terminal"` - Runs in background
+- `"terminal_mode": "show_commands"` - Prints commands without executing
+
+### Running in Current Terminal
+```bash
+# For single instance work
+HCOM_TERMINAL_MODE=same_terminal hcom open
+# This runs Claude directly in your current terminal
+```
+
+</details>
+
+<details>
+<summary><strong>🥔 Integrations</strong></summary>
+
+### Custom Terminal Integration
+
+Configure `terminal_command` in `~/.hcom/config.json` to use your preferred terminal:
+
+### iTerm2
+```json
+{
+  "terminal_command": "osascript -e 'tell app \"iTerm\" to create window with default profile command \"{env} {cmd}\"'"
+}
+```
+
+### Alacritty
+```json
+{
+  "terminal_command": "alacritty -e bash -c '{env} {cmd}'"
+}
+```
+
+### Windows Terminal
+```json
+{
+  "terminal_command": "wt new-tab cmd /k \"{env} & {cmd}\""
+}
+```
+
+### Kitty
+```json
+{
+  "terminal_command": "kitty -e bash -c '{env} {cmd}'"
+}
+```
+
+### tmux
+```json
+{
+  "terminal_command": "tmux new-window -n hcom '{env} {cmd}'"
+}
+```
+
+### screen
+```json
+{
+  "terminal_command": "screen -dmS hcom-$$ bash -c '{env} {cmd}'"
+}
+```
+
+### Available Placeholders
+- `{cmd}` - The claude command to execute
+- `{env}` - Environment variables (pre-formatted)
+- `{cwd}` - Current working directory
+
+</details>
+
+<details>
+<summary><strong>🥚 Troubleshooting</strong></summary>
+
+### Common Issues
+
+- **Claude stops responding**: Default idle timeout is 10 minutes (configure via `wait_timeout`)
+- **Message truncated**: Message size limit is 4096 chars (configure via `max_message_size`)
+
+### Debug Commands
+```bash
+# Run Claude in debug mode to see hook execution
+hcom open --claude-args "--debug"
+
+# View conversation log
+tail -f ~/.hcom/hcom.log
+
+# Check instance status
+cat ~/.hcom/hcom.json
+
+```
+</details>
+
+<details>
+<summary><strong>🦆 Remove</strong></summary>
+
+
+### Archive Conversation / Start New
+```bash
+hcom clear
+```
+
+### Remove all HCOM hooks
+```bash
+hcom clenup --all
+```
+
+### Remove hcom Completely
+1. Remove hcom: `rm /usr/local/bin/hcom` (or wherever you installed hcom)
+2. Remove all data: `rm -rf ~/.hcom`
+
+</details>
+
+## 🌮 License
+
+MIT License
+
+---

hcom-0.1.0/README.md

@@ -0,0 +1,335 @@
+# Claude Code Hook Comms
+
+Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
+
+## 🦆 What It Does
+
+Creates a group chat where you and multiple interactive Claude Code subagents can communicate with each other across different folders on your computer. Works on Mac, Linux, and Windows with zero dependencies.
+
+![Claude Hook Comms Example](screenshot.jpg)
+
+## 🦷 Key Features
+
+- **New Window** - Claude subagents open in new terminals
+- **Multi-Agent Communication** - Claude instances talk to each other across projects
+- **@Mention Targeting** - Send messages to specific subagents or teams
+- **Live Dashboard** - Real-time monitoring of all instances
+- **Zero Dependencies** - Pure Python stdlib, works everywhere
+
+## 🎪 Quick Start
+
+### Download
+```bash
+curl -sL https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py | sudo tee /usr/local/bin/hcom > /dev/null && sudo chmod +x /usr/local/bin/hcom
+```
+
+<details>
+<summary><strong>🦑 Windows</strong></summary>
+
+```powershell
+# Download Python file
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py" -OutFile "hcom.py"
+
+# Run python file directly
+python path/to/hcom.py open 2
+```
+</details>
+
+### Usage
+```bash
+# 1. Launch 3 Claude instances connected to group chat
+hcom open 3
+
+# 2. View/send messages in dashboard
+hcom watch
+```
+
+
+
+### Launch Claude Code Agents
+```bash
+# Launch researcher and code-writer from your .claude/agents
+hcom open researcher code-writer
+
+# Launch backend-coder frontend-coder orchestrator tester from your .claude/agents
+hcom open backend-coder frontend-coder orchestrator tester
+```
+
+### Launch Headless Mode
+```bash
+# Launch researcher and code-writer from your .claude/agents and work in background
+hcom open researcher code-writer --claude-args "-p"
+
+# Launch reviewer in headless mode with a prompt
+hcom open --claude-args "-p 'review git code changes when you get notified'"
+```
+
+### Launch with Options
+```bash
+# Launch researcher and code-writer from your .claude/agents and work in background
+hcom open researcher code-writer --prefix 'greenteam'
+hcom send '@greenteam get to work on green stuff'
+
+# Launch 2 claude code instances and 2 of your agents
+hcom open 2 backend-coder frontend-coder
+```
+
+
+## 🦐 Requirements
+
+- Python 3.6+
+- [Claude Code](https://claude.ai/code)
+
+
+## 🥨 Commands
+
+### Commands
+| Command | Description |
+|---------|-------------|
+| `hcom open [n]` | Launch n Claude instances (or named agents) |
+| `hcom watch` | View conversation/status dashboard |
+| `hcom clear` | Clear and archive conversation |
+| `hcom cleanup` | Remove HCOM hooks from current directory |
+
+### Automation Commands
+| Command | Description |
+|---------|-------------|
+| `hcom send 'message'` | Send message |
+| `hcom watch --logs` | View message history (non-interactive) |
+| `hcom watch --status` | Show instance status (non-interactive) |
+| `hcom watch --wait[=seconds]` | Wait for new messages (automation) |
+
+---
+
+<details>
+<summary><strong>🦖 Configuration</strong></summary>
+
+### Configuration
+
+Settings can be changed two ways:
+
+```bash
+# Method 1: Environment variable (termporary per-command/instance)
+HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-but-not-great-with-updates
+
+# Method 2: Config file (affects all instances)
+# Edit ~/.hcom/config.json
+```
+
+### All Settings
+
+### Config File Location
+
+`~/.hcom/config.json`
+
+| Setting | Default | Environment Variable | Description |
+|---------|---------|---------------------|-------------|
+| `wait_timeout` | 600 | `HCOM_WAIT_TIMEOUT` | How long instances wait for messages (seconds) |
+| `max_message_size` | 4096 | `HCOM_MAX_MESSAGE_SIZE` | Maximum message length |
+| `max_messages_per_delivery` | 20 | `HCOM_MAX_MESSAGES_PER_DELIVERY` | Messages delivered per batch |
+| `sender_name` | "bigboss" | `HCOM_SENDER_NAME` | Your name in chat |
+| `sender_emoji` | "🐳" | `HCOM_SENDER_EMOJI` | Your emoji icon |
+| `initial_prompt` | "Say hi" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |
+| `first_use_text` | "Essential, concise messages only. Say hi in hcom chat" | `HCOM_FIRST_USE_TEXT` | Welcome message for instances |
+| `terminal_mode` | "new_window" | `HCOM_TERMINAL_MODE` | How to launch terminals ("new_window", "same_terminal", "show_commands") |
+| `terminal_command` | null | `HCOM_TERMINAL_COMMAND` | Custom terminal command (see Terminal Integration) |
+| `cli_hints` | "" | `HCOM_CLI_HINTS` | Extra text added to CLI outputs |
+| `instance_hints` | "" | `HCOM_INSTANCE_HINTS` | Extra text added to instance messages |
+| `env_overrides` | {} | - | Additional environment variables for Claude |
+
+### Examples
+
+```bash
+# Change your name for one command
+HCOM_SENDER_NAME="reviewer" hcom send "LGTM!"
+
+# Make instances wait 30 minutes instead of 10
+HCOM_WAIT_TIMEOUT=1800 hcom open 3
+
+# Custom welcome message
+HCOM_FIRST_USE_TEXT="Debug session for issue #123" hcom open 2
+
+# Bigger messages
+HCOM_MAX_MESSAGE_SIZE=8192 hcom send "$(cat long_report.txt)"
+```
+
+### Status Indicators
+- ◉ **thinking** (cyan) - Processing input
+- ▷ **responding** (green) - Generating text response  
+- ▶ **executing** (green) - Running tools
+- ◉ **waiting** (blue) - Waiting for messages
+- ■ **blocked** (yellow) - Permission blocked
+- ○ **inactive** (red) - Timed out/dead
+
+</details>
+
+<details>
+<summary><strong>🎲 How It Works</strong></summary>
+
+### Hooks!
+
+hcom adds hooks to your project directory's `.claude/settings.local.json`:
+
+1. **Sending**: Claude writes messages with `echo "HCOM_SEND:message"` - captured by PostToolUse hook
+2. **Receiving**: Other Claudes get notified via Stop hook
+3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages
+
+- **Identity**: Each instance gets a unique name based on conversation UUID (e.g., "hovoa7")
+- **Persistence**: Names persist across `claude --resume` maintaining conversation context
+- **Status Detection**: Notification hook tracks permission requests and activity
+
+### Architecture
+- **Single conversation** - All instances share one global conversation
+- **Opt-in participation** - Only instances launched with `hcom open` join the chat
+- **@-mention filtering** - Target messages to specific instances or teams
+
+### File Structure
+```
+~/.hcom/                             
+├── hcom.log       # Conversation log
+├── hcom.json      # Instance tracking
+└── config.json    # Configuration
+
+your-project/  
+└── .claude/
+    └── settings.local.json  # hcom hooks configuration
+```
+
+</details>
+
+
+<details>
+<summary><strong>🧈 Launching Claude Code</strong></summary>
+
+### Launching Claude Code
+
+Use `hcom open` to automatically launch Claude instances with proper setup:
+
+```bash
+# Launch 3 generic instances
+hcom open 3
+
+# Launch with custom terminal mode
+hcom open 2  # Uses terminal_mode from config
+
+# Launch named agents
+hcom open writer researcher
+```
+
+Configure terminal behavior in `~/.hcom/config.json`:
+- `"terminal_mode": "new_window"` - Opens new terminal windows (default)
+- `"terminal_mode": "same_terminal"` - Runs in background
+- `"terminal_mode": "show_commands"` - Prints commands without executing
+
+### Running in Current Terminal
+```bash
+# For single instance work
+HCOM_TERMINAL_MODE=same_terminal hcom open
+# This runs Claude directly in your current terminal
+```
+
+</details>
+
+<details>
+<summary><strong>🥔 Integrations</strong></summary>
+
+### Custom Terminal Integration
+
+Configure `terminal_command` in `~/.hcom/config.json` to use your preferred terminal:
+
+### iTerm2
+```json
+{
+  "terminal_command": "osascript -e 'tell app \"iTerm\" to create window with default profile command \"{env} {cmd}\"'"
+}
+```
+
+### Alacritty
+```json
+{
+  "terminal_command": "alacritty -e bash -c '{env} {cmd}'"
+}
+```
+
+### Windows Terminal
+```json
+{
+  "terminal_command": "wt new-tab cmd /k \"{env} & {cmd}\""
+}
+```
+
+### Kitty
+```json
+{
+  "terminal_command": "kitty -e bash -c '{env} {cmd}'"
+}
+```
+
+### tmux
+```json
+{
+  "terminal_command": "tmux new-window -n hcom '{env} {cmd}'"
+}
+```
+
+### screen
+```json
+{
+  "terminal_command": "screen -dmS hcom-$$ bash -c '{env} {cmd}'"
+}
+```
+
+### Available Placeholders
+- `{cmd}` - The claude command to execute
+- `{env}` - Environment variables (pre-formatted)
+- `{cwd}` - Current working directory
+
+</details>
+
+<details>
+<summary><strong>🥚 Troubleshooting</strong></summary>
+
+### Common Issues
+
+- **Claude stops responding**: Default idle timeout is 10 minutes (configure via `wait_timeout`)
+- **Message truncated**: Message size limit is 4096 chars (configure via `max_message_size`)
+
+### Debug Commands
+```bash
+# Run Claude in debug mode to see hook execution
+hcom open --claude-args "--debug"
+
+# View conversation log
+tail -f ~/.hcom/hcom.log
+
+# Check instance status
+cat ~/.hcom/hcom.json
+
+```
+</details>
+
+<details>
+<summary><strong>🦆 Remove</strong></summary>
+
+
+### Archive Conversation / Start New
+```bash
+hcom clear
+```
+
+### Remove all HCOM hooks
+```bash
+hcom clenup --all
+```
+
+### Remove hcom Completely
+1. Remove hcom: `rm /usr/local/bin/hcom` (or wherever you installed hcom)
+2. Remove all data: `rm -rf ~/.hcom`
+
+</details>
+
+## 🌮 License
+
+MIT License
+
+---