# Claude Code Hook Comms
Lightweight CLI tool for real-time communication between claude code [subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) 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.
## 🦷 Features
- **Multi-Terminal Launch** - Launch claude code subagents in new terminals
- **Live Dashboard** - Real-time monitoring of all instances
- **Multi-Agent Communication** - Claude instances talk to each other across projects
- **@Mention Targeting** - Send messages to specific subagents or teams
- **Zero Dependencies** - Pure Python stdlib, works everywhere
## 🎪 Quick Start
### Use Without Installing
```bash
# Launch 3 default Claude instances connected to group chat
uvx hcom open 3
# Launch researcher and code-writer from your .claude/agents
uvx hcom open researcher code-writer
# View/send messages in dashboard
uvx hcom watch
```
### Install
```bash
# uv
uv tool install hcom
# or pip
pip install hcom
# then use with:
hcom open 3
```
## 🦐 Requirements
- Python 3.6+
- [Claude Code](https://claude.ai/code)
## 🗿 More Examples
```bash
# Launch 2 generic instances + 2 specific agents
hcom open 2 backend-coder frontend-coder
# Launch multiple of the same agent
hcom open reviewer reviewer reviewer # 3 separate reviewers
# Launch agents in background with specific prompts
hcom open test-writer --claude-args "-p 'write tests for any new code'"
# Launch watchers that respond to notifications
hcom open reviewer --claude-args "-p 'review when @mentioned'"
# Pass multiple Claude flags
hcom open orchestrator --claude-args "--model claude-3-opus
--resume session_id"
# Launch in specific directories
cd backend && hcom open api-specialist
cd ../frontend && hcom open ui-specialist
# Create named teams that can be @mentioned
cd ~/api && hcom open --prefix api debugger
cd ~/auth && hcom open --prefix auth debugger
# Message specific teams
hcom send "@api login works but API fails" # or in dashboard: hcom watch
```
## 🥨 Commands
| Command | Description |
|---------|-------------|
| `hcom open [n]` | Launch n Claude instances (or named agents) |
| `hcom watch` | 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 [timeout]` | Wait and notify for new messages |
---
<details>
<summary><strong>🦖 Configuration</strong></summary>
### Configuration
Settings can be changed two ways:
#### Method 1: Environment variable (temporary, per-command/instance)
```bash
HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-but-not-great-with-updates
```
#### Method 2: Config file (persistent, affects all instances)
### 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" | `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 Options) |
| `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 Code |
### 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 `--resume` maintaining conversation context
- **Status Detection**: Notification hook tracks permission requests and activity
- **Agents**: When you run `hcom open researcher`, it loads an interactive claude session with a system prompt from `.claude/agents/researcher.md` (local) or `~/.claude/agents/researcher.md` (global)
### Architecture
- **Single conversation** - All instances share one global conversation
- **Opt-in participation** - Only claude code 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>🥔 Terminal Options</strong></summary>
### Terminal Mode
Configure terminal behavior in `~/.hcom/config.json`:
- `"terminal_mode": "new_window"` - Opens new terminal windows (default)
- `"terminal_mode": "same_terminal"` - Opens in current terminal
- `"terminal_mode": "show_commands"` - Prints commands without executing
### Default Terminals
- **macOS**: Terminal.app
- **Linux**: gnome-terminal, konsole, or xterm
- **Windows**: Windows Terminal / PowerShell
### Running in Current Terminal
```bash
# For single instances
HCOM_TERMINAL_MODE=same_terminal hcom open
```
### Custom Terminal Examples
Configure `terminal_command` in `~/.hcom/config.json` to use your preferred terminal:
### iTerm2
```json
{
"terminal_command": "osascript -e 'tell app \"iTerm2\" to create window with default profile' -e 'tell current session of current window to write text \"{env} {cmd}\"'"
}
```
### Alacritty
```json
{
"terminal_command": "alacritty -e sh -c '{env} {cmd}'"
}
```
### Kitty
```json
{
"terminal_command": "kitty sh -c '{env} {cmd}'"
}
```
### WezTerm
```json
{
"terminal_command": "wezterm cli spawn --new-window -- sh -c '{env} {cmd}'"
}
```
### tmux
```json
{
"terminal_command": "tmux new-window -n hcom sh -c '{env} {cmd}'"
}
```
### Available Placeholders
- `{cmd}` - The claude command to execute
- `{env}` - Environment variables (pre-formatted as `VAR1='value1' VAR2='value2'`)
- `{cwd}` - Current working directory
### Notes
- Custom commands must exit with code 0 for success
- The `{env}` placeholder contains shell-quoted environment variables
- Most terminals require wrapping the command in `sh -c` to handle environment variables correctly
</details>
<details>
<summary><strong>🦆 Remove</strong></summary>
### Archive Conversation / Start New
```bash
hcom clear
```
### Remove HCOM hooks from current directory
```bash
hcom cleanup
```
### Remove HCOM hooks from all directories
```bash
hcom cleanup --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
---
Raw data
{
"_id": null,
"home_page": null,
"name": "hcom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "claude, claude-code, hooks, agents, cli, multi-agent-orchestration",
"author": null,
"author_email": "aannoo <your@email.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/07/0bd0b159a30181cb8b15851f9d6093d0105a4d1fab13ddb6cf1049461f82/hcom-0.1.3.tar.gz",
"platform": null,
"description": "# Claude Code Hook Comms\n\nLightweight CLI tool for real-time communication between claude code [subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).\n\n## \ud83e\udd86 What It Does\n\nCreates 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.\n\n\n\n## \ud83e\uddb7 Features\n\n- **Multi-Terminal Launch** - Launch claude code subagents in new terminals\n- **Live Dashboard** - Real-time monitoring of all instances\n- **Multi-Agent Communication** - Claude instances talk to each other across projects\n- **@Mention Targeting** - Send messages to specific subagents or teams\n- **Zero Dependencies** - Pure Python stdlib, works everywhere\n\n## \ud83c\udfaa Quick Start\n\n### Use Without Installing\n```bash\n# Launch 3 default Claude instances connected to group chat\nuvx hcom open 3\n\n# Launch researcher and code-writer from your .claude/agents\nuvx hcom open researcher code-writer\n\n# View/send messages in dashboard\nuvx hcom watch\n```\n\n### Install\n\n```bash\n# uv\nuv tool install hcom\n# or pip\npip install hcom\n# then use with:\nhcom open 3\n```\n\n\n## \ud83e\udd90 Requirements\n\n- Python 3.6+\n- [Claude Code](https://claude.ai/code)\n\n\n## \ud83d\uddff More Examples\n\n```bash\n# Launch 2 generic instances + 2 specific agents\nhcom open 2 backend-coder frontend-coder\n\n# Launch multiple of the same agent\nhcom open reviewer reviewer reviewer # 3 separate reviewers\n\n# Launch agents in background with specific prompts\nhcom open test-writer --claude-args \"-p 'write tests for any new code'\"\n\n# Launch watchers that respond to notifications\nhcom open reviewer --claude-args \"-p 'review when @mentioned'\"\n\n# Pass multiple Claude flags\nhcom open orchestrator --claude-args \"--model claude-3-opus \n--resume session_id\"\n\n# Launch in specific directories\ncd backend && hcom open api-specialist\ncd ../frontend && hcom open ui-specialist\n\n# Create named teams that can be @mentioned\ncd ~/api && hcom open --prefix api debugger\ncd ~/auth && hcom open --prefix auth debugger\n\n# Message specific teams\nhcom send \"@api login works but API fails\" # or in dashboard: hcom watch\n```\n\n\n## \ud83e\udd68 Commands\n\n| Command | Description |\n|---------|-------------|\n| `hcom open [n]` | Launch n Claude instances (or named agents) |\n| `hcom watch` | Conversation/status dashboard |\n| `hcom clear` | Clear and archive conversation |\n| `hcom cleanup` | Remove HCOM hooks from current directory |\n\n### Automation Commands\n| Command | Description |\n|---------|-------------|\n| `hcom send 'message'` | Send message |\n| `hcom watch --logs` | View message history (non-interactive) |\n| `hcom watch --status` | Show instance status (non-interactive) |\n| `hcom watch --wait [timeout]` | Wait and notify for new messages |\n\n---\n\n<details>\n<summary><strong>\ud83e\udd96 Configuration</strong></summary>\n\n### Configuration\n\nSettings can be changed two ways:\n\n#### Method 1: Environment variable (temporary, per-command/instance)\n\n\n```bash\nHCOM_INSTANCE_HINTS=\"always update chat with progress\" hcom open nice-subagent-but-not-great-with-updates\n```\n\n#### Method 2: Config file (persistent, affects all instances)\n\n### Config File Location\n\n`~/.hcom/config.json`\n\n| Setting | Default | Environment Variable | Description |\n|---------|---------|---------------------|-------------|\n| `wait_timeout` | 600 | `HCOM_WAIT_TIMEOUT` | How long instances wait for messages (seconds) |\n| `max_message_size` | 4096 | `HCOM_MAX_MESSAGE_SIZE` | Maximum message length |\n| `max_messages_per_delivery` | 20 | `HCOM_MAX_MESSAGES_PER_DELIVERY` | Messages delivered per batch |\n| `sender_name` | \"bigboss\" | `HCOM_SENDER_NAME` | Your name in chat |\n| `sender_emoji` | \"\ud83d\udc33\" | `HCOM_SENDER_EMOJI` | Your emoji icon |\n| `initial_prompt` | \"Say hi\" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |\n| `first_use_text` | \"Essential, concise messages only\" | `HCOM_FIRST_USE_TEXT` | Welcome message for instances |\n| `terminal_mode` | \"new_window\" | `HCOM_TERMINAL_MODE` | How to launch terminals (\"new_window\", \"same_terminal\", \"show_commands\") |\n| `terminal_command` | null | `HCOM_TERMINAL_COMMAND` | Custom terminal command (see Terminal Options) |\n| `cli_hints` | \"\" | `HCOM_CLI_HINTS` | Extra text added to CLI outputs |\n| `instance_hints` | \"\" | `HCOM_INSTANCE_HINTS` | Extra text added to instance messages |\n| `env_overrides` | {} | - | Additional environment variables for Claude Code |\n\n### Examples\n\n```bash\n# Change your name for one command\nHCOM_SENDER_NAME=\"reviewer\" hcom send \"LGTM!\"\n\n# Make instances wait 30 minutes instead of 10\nHCOM_WAIT_TIMEOUT=1800 hcom open 3\n\n# Custom welcome message\nHCOM_FIRST_USE_TEXT=\"Debug session for issue #123\" hcom open 2\n\n# Bigger messages\nHCOM_MAX_MESSAGE_SIZE=8192 hcom send \"$(cat long_report.txt)\"\n```\n\n### Status Indicators\n- \u25c9 **thinking** (cyan) - Processing input\n- \u25b7 **responding** (green) - Generating text response \n- \u25b6 **executing** (green) - Running tools\n- \u25c9 **waiting** (blue) - Waiting for messages\n- \u25a0 **blocked** (yellow) - Permission blocked\n- \u25cb **inactive** (red) - Timed out/dead\n\n</details>\n\n<details>\n<summary><strong>\ud83c\udfb2 How It Works</strong></summary>\n\n### Hooks!\n\nhcom adds hooks to your project directory's `.claude/settings.local.json`:\n\n1. **Sending**: Claude writes messages with `echo \"HCOM_SEND:message\"` - captured by PostToolUse hook\n2. **Receiving**: Other Claudes get notified via Stop hook\n3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages\n\n- **Identity**: Each instance gets a unique name based on conversation UUID (e.g., \"hovoa7\")\n- **Persistence**: Names persist across `--resume` maintaining conversation context\n- **Status Detection**: Notification hook tracks permission requests and activity\n- **Agents**: When you run `hcom open researcher`, it loads an interactive claude session with a system prompt from `.claude/agents/researcher.md` (local) or `~/.claude/agents/researcher.md` (global)\n\n### Architecture\n- **Single conversation** - All instances share one global conversation\n- **Opt-in participation** - Only claude code instances launched with `hcom open` join the chat\n- **@-mention filtering** - Target messages to specific instances or teams\n\n### File Structure\n```\n~/.hcom/ \n\u251c\u2500\u2500 hcom.log # Conversation log\n\u251c\u2500\u2500 hcom.json # Instance tracking\n\u2514\u2500\u2500 config.json # Configuration\n\nyour-project/ \n\u2514\u2500\u2500 .claude/\n \u2514\u2500\u2500 settings.local.json # hcom hooks configuration\n```\n\n</details>\n\n\n<details>\n<summary><strong>\ud83e\udd54 Terminal Options</strong></summary>\n\n### Terminal Mode\n\nConfigure terminal behavior in `~/.hcom/config.json`:\n- `\"terminal_mode\": \"new_window\"` - Opens new terminal windows (default)\n- `\"terminal_mode\": \"same_terminal\"` - Opens in current terminal\n- `\"terminal_mode\": \"show_commands\"` - Prints commands without executing\n\n### Default Terminals\n\n- **macOS**: Terminal.app\n- **Linux**: gnome-terminal, konsole, or xterm\n- **Windows**: Windows Terminal / PowerShell\n\n### Running in Current Terminal\n```bash\n# For single instances\nHCOM_TERMINAL_MODE=same_terminal hcom open\n```\n\n### Custom Terminal Examples\n\nConfigure `terminal_command` in `~/.hcom/config.json` to use your preferred terminal:\n\n### iTerm2\n```json\n{\n \"terminal_command\": \"osascript -e 'tell app \\\"iTerm2\\\" to create window with default profile' -e 'tell current session of current window to write text \\\"{env} {cmd}\\\"'\"\n}\n```\n\n### Alacritty\n```json\n{\n \"terminal_command\": \"alacritty -e sh -c '{env} {cmd}'\"\n}\n```\n\n### Kitty\n```json\n{\n \"terminal_command\": \"kitty sh -c '{env} {cmd}'\"\n}\n```\n\n### WezTerm\n```json\n{\n \"terminal_command\": \"wezterm cli spawn --new-window -- sh -c '{env} {cmd}'\"\n}\n```\n\n### tmux\n```json\n{\n \"terminal_command\": \"tmux new-window -n hcom sh -c '{env} {cmd}'\"\n}\n```\n\n### Available Placeholders\n- `{cmd}` - The claude command to execute\n- `{env}` - Environment variables (pre-formatted as `VAR1='value1' VAR2='value2'`)\n- `{cwd}` - Current working directory\n\n### Notes\n- Custom commands must exit with code 0 for success\n- The `{env}` placeholder contains shell-quoted environment variables\n- Most terminals require wrapping the command in `sh -c` to handle environment variables correctly\n\n</details>\n\n\n<details>\n<summary><strong>\ud83e\udd86 Remove</strong></summary>\n\n\n### Archive Conversation / Start New\n```bash\nhcom clear\n```\n\n### Remove HCOM hooks from current directory\n```bash\nhcom cleanup\n```\n\n### Remove HCOM hooks from all directories\n```bash\nhcom cleanup --all\n```\n\n### Remove hcom Completely\n1. Remove hcom: `rm /usr/local/bin/hcom` (or wherever you installed hcom)\n2. Remove all data: `rm -rf ~/.hcom`\n\n</details>\n\n## \ud83c\udf2e License\n\nMIT License\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight CLI tool for real-time messaging between Claude Code subagents using hooks",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/aannoo/claude-hook-comms",
"Issues": "https://github.com/aannoo/claude-hook-comms/issues",
"Repository": "https://github.com/aannoo/claude-hook-comms"
},
"split_keywords": [
"claude",
" claude-code",
" hooks",
" agents",
" cli",
" multi-agent-orchestration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fe72d87ecf2bb3dfafd469a86b66c973ddcd1641021828dbdd01b035e08846c3",
"md5": "bb65b3282cffe988e4995f13666d19ec",
"sha256": "06edaa165acdd6aea01626c061ee6f756ea705aec1b38c0fc16f202f625b0544"
},
"downloads": -1,
"filename": "hcom-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb65b3282cffe988e4995f13666d19ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 21709,
"upload_time": "2025-08-01T17:27:10",
"upload_time_iso_8601": "2025-08-01T17:27:10.073951Z",
"url": "https://files.pythonhosted.org/packages/fe/72/d87ecf2bb3dfafd469a86b66c973ddcd1641021828dbdd01b035e08846c3/hcom-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d070bd0b159a30181cb8b15851f9d6093d0105a4d1fab13ddb6cf1049461f82",
"md5": "d02ccdb62d482a66ea970f3ec2cbd1f6",
"sha256": "e846c748cd9fa5a4c65bb313fec223814bae47075bfba71bd9098992ef4dd48c"
},
"downloads": -1,
"filename": "hcom-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "d02ccdb62d482a66ea970f3ec2cbd1f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 25220,
"upload_time": "2025-08-01T17:27:11",
"upload_time_iso_8601": "2025-08-01T17:27:11.083056Z",
"url": "https://files.pythonhosted.org/packages/0d/07/0bd0b159a30181cb8b15851f9d6093d0105a4d1fab13ddb6cf1049461f82/hcom-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 17:27:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aannoo",
"github_project": "claude-hook-comms",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hcom"
}
JSON
