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

---
