hcom 0.4.2.post3

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

hcom - Claude Hook Comms

CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks. Works on Mac, Linux, Windows, and Android with zero dependencies.

🥦 Usage

Run without installing (uv)

uvx hcom 2

Install

pip install hcom  # or: uv tool install hcom
# then:
hcom 2  # or tell claude to run hcom start

Commands
hcom <n>	Launch n instances (default 1)
hcom watch	View live dashboard and messaging
hcom stop	Disable hcom chat for instance
hcom start	Enable hcom chat for instance
hcom reset	Stop all + archive logs + remove hooks + clear config

🦆 What It Does

hcom adds hooks to ~/.claude/settings.json and launches terminals with Claude Code that remain active, waiting to respond to messages in the shared chat. Normal Claude Code opened with claude remains unaffected by hcom, but can opt-in via hcom start and opt-out with hcom stop.

Interactive subagents in their own terminal

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

Persistent headless instances

hcom 1 claude -p   # Launch one headless instance (default 30min timeout)
hcom watch   # See what it's doing
hcom stop   # Let it die earlier than timeout

Groups and direct messages

HCOM_TAG=cool hcom 2   # Creates cool-hovoa7 & cool-homab8
hcom send '@cool hi, you are cool'
hcom send '@homab8 hi, you are cooler'

Toggle HCOM in Claude Code

claude  # Start normal Claude Code
'run hcom start'   # Start HCOM for this instance to receive messages
'run hcom stop'   # Stop HCOM for this instance, continue as normal claude code

---

🦷 Features

• Multi-Terminal Launch - Launch Claude Code subagents in new terminals
• Background Mode - Run headless instances without terminal windows
• Interactive subagents - Run subagents in their own terminal window
• Live Dashboard - Real-time monitoring and messaging
• Multi-Agent Communication - Instances talk to each other via shared chat
• @Mention Targeting - Send messages to specific instances or teams
• Session Persistence - Resume previous conversations automatically
• Zero Dependencies - Pure Python stdlib, works everywhere
• Cross-platform - Native support for Windows, WSL, macOS, Linux, Android

🥨 All Commands

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

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   Initial prompt
  HCOM_TIMEOUT=secs  Timeout in seconds (default: 1800)

🗿 Examples

# Launch 3 headless instances that time out after 60 seconds of inactivity
HCOM_TIMEOUT=60 hcom 3 claude -p
# Stop all instances
hcom stop all

# Launch multiple of the same subagent
HCOM_AGENT=reviewer hcom 3

# Launch mixed agents with team tag
HCOM_TAG=api HCOM_AGENT=backend,frontend hcom 1

# Launch instance with specific prompt
HCOM_PROMPT='write tests' HCOM_AGENT=test-writer hcom 1

# Pass claude args
hcom 1 claude --resume session_id  # Resume instance (hcom chat continues)

# Text appended to all messages received by instance
HCOM_HINTS="remember where you came from" hcom 1

# Start hcom communication with shared context forked from a checkpoint
HCOM_TAG=clone hcom 3 claude --resume session_id --fork-session
# Creates: clone-skal7, clone-hova3, clone-koe2. Mention all: @clone

🦖 Configuration

Configuration

Config file: ~/.hcom/config.env

All HCOM_* settings work from config file (persistent) or environment variable (temporary). Environment variables override config file.

Setting	Description	Default
HCOM_TIMEOUT	Instance wait timeout (1-86400 seconds)	1800
HCOM_TERMINAL	Terminal mode: new, here, print, or custom {script}	new
HCOM_PROMPT	Initial prompt for new instances	say hi in hcom chat
HCOM_HINTS	Text appended to all messages	(empty)
HCOM_TAG	Group tag (creates tag-* instances)	(empty)
HCOM_AGENT	Agent type, comma-separated	generic

Any other environment variables in config.env are passed to Claude Code instances (e.g., ANTHROPIC_MODEL).

Examples

# Temporary override for one command
HCOM_TIMEOUT=60 hcom 3

# Set persistent config
echo "HCOM_TIMEOUT=60" >> ~/.hcom/config.env
echo "HCOM_TERMINAL=here" >> ~/.hcom/config.env

# Pass Claude Code env vars
ANTHROPIC_MODEL=opus hcom 3

Windows PowerShell:

# Temporary environment variable
$env:HCOM_TERMINAL="here"; hcom 1
$env:HCOM_TIMEOUT="60"; hcom 3

Status Indicators

When running hcom watch, each instance shows its current state:

• ▶ active (green) - Working (processing/executing)
• ▷ delivered (cyan) - Just received a message
• ◉ waiting (blue) - Waiting for messages
• ■ blocked (yellow) - Permission request pending
• ○ inactive (red) - Closed/timed out/ended
• ○ unknown (gray) - No status data or stale
• (bg) suffix - Instance running in background headless mode

🎲 How It Works

Hooks!

hcom adds hooks to ~/.claude/settings.json:

1. Sending: Claude uses hcom send "message" to communicate
2. Receiving: Other Claudes get notified via Stop hook or immediate delivery after sending
3. Waiting: Stop hook keeps Claude in a waiting state for new messages

• Identity: Each instance gets a unique name based on session ID (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_AGENT=researcher hcom 1, it loads an interactive Claude session with a system prompt from .claude/agents/researcher.md (local) or ~/.claude/agents/researcher.md (global). Specified model: and tools: are carried over

Architecture

• Single conversation - All instances share one global conversation
• Opt-in participation - Only Claude Code instances launched with hcom join automatically, normal instances can use hcom start/stop
• @-mention filtering - Target messages to specific instances or teams

File Structure

~/.hcom/
├── hcom.log       # Conversation log
├── instances/     # Instance tracking
├── logs/          # Background process logs
├── config.env     # Configuration
└── archive/       # Archived sessions

~/.claude/
└── settings.json  # hcom hooks (global)

🥔 Terminal Options

Terminal Mode

Configure terminal behavior in ~/.hcom/config.env:

• HCOM_TERMINAL=new - Opens new terminal window(s) (default)
• HCOM_TERMINAL=here - Opens in current terminal
• HCOM_TERMINAL=print - Prints commands instead of launching

Running in current terminal temporarily

# For single instances
HCOM_TERMINAL=here hcom 1

Default Terminals

• macOS: Terminal.app
• Linux: gnome-terminal, konsole, or xterm
• Windows & WSL: Windows Terminal / Git Bash
• Android: Termux

Custom Terminals

Configure in ~/.hcom/config.env (permanent) or environment variables (temporary).

How to use this

The {script} placeholder is replaced by HCOM with the path to a temporary bash script that launches Claude Code.

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

Example template: your_terminal_command --execute "bash {script}"

Custom Terminal Examples

iTerm2

HCOM_TERMINAL="open -a iTerm {script}"

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

# 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}"

# 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

HCOM_TERMINAL="tmux new-window -n hcom {script}"

# tmux commands work inside tmux, start a session with:
tmux new-session 'hcom 3' # each instance opens in new tmux window

# Or one time split-panes:
# Start tmux with split panes and 3 claude instances in hcom chat
HCOM_TERMINAL="tmux split-window -h {script}" hcom 3

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 1

---

⚗️ Remove

Archive Conversation / Start New

hcom stop all

Stop Running Instances

# Stop specific instance
hcom stop hovoa7

# Stop all and archive
hcom stop all

Start Stopped Instances

# Start specific instance
hcom start hovoa7

Remove HCOM hooks

# Stop all, archive conversation, remove hooks, clear config
hcom reset

Remove hcom Completely

1. Remove hcom: rm /usr/local/bin/hcom (or wherever you installed hcom)
2. Remove all data: rm -rf ~/.hcom

🦐 Requirements

• Python 3.10+
• Claude Code

🌮 License

• MIT License

---