hcom 0.5.0

CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks

hcom — Claude Hook Comms

Launch multiple Claude Code terminals (or headless) 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

claude 'run hcom start'

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 <n>	Launch n instances
hcom watch	Live dashboard and messaging
hcom stop [alias|all]	Disable participation
hcom start [alias]	Enable participation
hcom reset [logs|hooks|config]	Safe Cleanup

Examples

Interactive subagents

# Claude Code subagents from .claude/agents
HCOM_AGENT=planner,code-writer,reviewer hcom 1

Persistent headless instances

hcom 1 claude -p    # default 30min timeout
hcom watch          # See what it's doing
hcom stop           # Let it die earlier than timeout

@-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

[ENV_VARS] hcom <COUNT> [claude <ARGS>]

Usage: [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
       hcom watch [--logs|--status|--wait [SEC]]
       hcom send "message"
       hcom stop [alias|all] [--force]
       hcom start [alias]
       hcom reset [logs|hooks|config]

Launch Examples:
  hcom 3             Open 3 terminals with claude connected to hcom
  hcom 3 claude -p                            + Background/headless
  HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
  claude 'run hcom start'    claude code with prompt will also work

Commands:
  watch              Interactive messaging/status dashboard
    --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
    --force          Emergency stop (denies Bash tool)

  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_PROMPT=text   "Say hi in hcom chat" (default)
  HCOM_HINTS=text    Text appended to all messages received by instance
  HCOM_TIMEOUT=secs  Time until disconnected from hcom chat (default 1800s / 30mins)

  ANTHROPIC_MODEL=opus # Passed through to Claude Code

  Persist Env Vars in `~/.hcom/config.env`

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 (iTerm2)

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`

---

Requirements

• Python 3.10+
• Claude Code

License

MIT