hcom 0.1.0

Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using hooks

Claude Code Hook Comms

Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using 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.

🦷 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

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

🦑 Windows

# 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

Usage

# 1. Launch 3 Claude instances connected to group chat
hcom open 3

# 2. View/send messages in dashboard
hcom watch

Launch Claude Code Agents

# 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

# 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

# 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

🥨 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)

---

🦖 Configuration

Configuration

Settings can be changed two ways:

# 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

# 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

🎲 How It Works

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

🧈 Launching Claude Code

Launching Claude Code

Use hcom open to automatically launch Claude instances with proper setup:

# 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

# For single instance work
HCOM_TERMINAL_MODE=same_terminal hcom open
# This runs Claude directly in your current terminal

🥔 Integrations

Custom Terminal Integration

Configure terminal_command in ~/.hcom/config.json to use your preferred terminal:

iTerm2

{
  "terminal_command": "osascript -e 'tell app \"iTerm\" to create window with default profile command \"{env} {cmd}\"'"
}

Alacritty

{
  "terminal_command": "alacritty -e bash -c '{env} {cmd}'"
}

Windows Terminal

{
  "terminal_command": "wt new-tab cmd /k \"{env} & {cmd}\""
}

Kitty

{
  "terminal_command": "kitty -e bash -c '{env} {cmd}'"
}

tmux

{
  "terminal_command": "tmux new-window -n hcom '{env} {cmd}'"
}

screen

{
  "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

🥚 Troubleshooting

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

# 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

🦆 Remove

Archive Conversation / Start New

hcom clear

Remove all HCOM hooks

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

🌮 License

MIT License

---