Metadata-Version: 2.4
Name: hcom
Version: 0.4.2.post3
Summary: CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks
Author: aannoo
License-Expression: MIT
Project-URL: Homepage, https://github.com/aannoo/claude-hook-comms
Project-URL: Repository, https://github.com/aannoo/claude-hook-comms
Project-URL: Issues, https://github.com/aannoo/claude-hook-comms/issues
Project-URL: Documentation, https://github.com/aannoo/claude-hook-comms#readme
Keywords: claude,claude-code,hooks,agents,cli,multi-agent,orchestration,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# hcom - Claude Hook Comms

[![PyPI - Version](https://img.shields.io/pypi/v/hcom)](https://pypi.org/project/hcom/)
 [![PyPI - License](https://img.shields.io/pypi/l/hcom)](https://opensource.org/license/MIT) [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org) [![DeepWiki](https://img.shields.io/badge/DeepWiki-aannoo%2Fclaude--hook--comms-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/aannoo/claude-hook-comms)

CLI tool for launching multiple Claude Code terminals with interactive [subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents), headless persistence, and real-time communication via [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Works on Mac, Linux, Windows, and Android with zero dependencies.

![Claude Code Hook Comms Example](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screencapture.gif)

## 🥦 Usage

**Run without installing** ([uv](https://docs.astral.sh/uv/#installation))
```bash
uvx hcom 2
```

**Install**
```bash
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
```bash
# Launch subagents from your .claude/agents
HCOM_AGENT=planner,code-writer,reviewer hcom 1
```

### Persistent headless instances
```bash
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
```bash
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
```bash
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
```

---


<details>
<summary><strong>🦷 Features</strong></summary>

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

</details>

<details>
<summary><strong>🥨 All Commands</strong></summary>

```bash
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)
```

</details>



<details>
<summary><strong>🗿 Examples</strong></summary>

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

</details>

<details>
<summary><strong>🦖 Configuration</strong></summary>

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

```bash
# 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**:
```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

</details>

<details>
<summary><strong>🎲 How It Works</strong></summary>

### 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
```plaintext
~/.hcom/
├── hcom.log       # Conversation log
├── instances/     # Instance tracking
├── logs/          # Background process logs
├── config.env     # Configuration
└── archive/       # Archived sessions

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

</details>


<details>
<summary><strong>🥔 Terminal Options</strong></summary>

### 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
```bash
# 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
```bash
HCOM_TERMINAL="open -a iTerm {script}"
```

#### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)
```bash
HCOM_TERMINAL="ttab {script}"
```

#### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)
```bash
HCOM_TERMINAL="wttab {script}"
```

#### More
```bash
# 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
```bash
HCOM_TERMINAL="tmux new-window -n hcom {script}"
```
```bash
# 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](https://f-droid.org/packages/com.termux/) from F-Droid (not Google Play)
2. Setup:
   ```bash
   pkg install python nodejs
   npm install -g @anthropic-ai/claude-cli
   pip install hcom
   ```
3. Enable:
   ```bash
   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`

---

</details>


<details>
<summary><strong>⚗️ Remove</strong></summary>


### Archive Conversation / Start New
```bash
hcom stop all
```

### Stop Running Instances
```bash
# Stop specific instance
hcom stop hovoa7

# Stop all and archive
hcom stop all
```

### Start Stopped Instances
```bash
# Start specific instance
hcom start hovoa7
```

### Remove HCOM hooks
```bash
# 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`

</details>

## 🦐 Requirements

- Python 3.10+
- [Claude Code](https://claude.ai/code)



## 🌮 License

- MIT License

---
