hcom 0.6.1

Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.

hcom — Claude Hook Comms

Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.

Start

Run without installing

uvx hcom 2

Install

pip install hcom   # or: uv tool install hcom

Use

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

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

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

HCOM_AGENT=code-writer hcom 1
HCOM_AGENT=reviewer hcom 1

@-mention: groups and direct

HCOM_TAG=cooltag hcom 2
hcom send '@cooltag hi, you both are cool'
hcom send '@john you are cooler'

toggle inside claude code

claude              # Normal Claude Code
'run hcom start'    # Opt-in to receive messages
'run hcom stop'     # Opt-out, continue as normal claude code

---

All commands

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

---

Terminal Options

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 (new tab instead of new window in Terminal.app)

HCOM_TERMINAL="ttab {script}"

wttab (new tab in Windows Terminal)

HCOM_TERMINAL="wttab {script}"

More

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

#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`

---

License

MIT