| Name | hcom JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks |
| upload_time | 2025-10-06 04:30:25 |
| maintainer | None |
| docs_url | None |
| author | aannoo |
| requires_python | >=3.10 |
| license | None |
| keywords |
claude
claude-code
hooks
agents
cli
multi-agent
orchestration
terminal
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# hcom - Claude Hook Comms
[](https://pypi.org/project/hcom/)
[](https://opensource.org/license/MIT) [](https://python.org) [](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.
## 🥦 Usage
**Run without installing** ([uv](https://docs.astral.sh/uv/#installation))
```bash
uvx hcom open 2
```
**Install** (optional)
```bash
pip install hcom
hcom open 2
```
| Commands | |
|---------|-------------|
| `hcom open [n]` | Launch `n` instances or named agents |
| `hcom watch` | View live dashboard and messaging |
| `hcom clear` | Clear and start new conversation |
| `hcom cleanup` | Safely remove hcom hooks, preserving your project settings |
## 🦆 What It Does
`hcom open` adds hooks to the `.claude/settings.local.json` file in the current folder 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.
### Subagents in their own terminal
```bash
# Launch subagents from your .claude/agents
hcom open planner code-writer reviewer
```
### Persistent headless instances
```bash
# Launch one headless instance (default 30min timeout)
hcom open -p
```
### Groups and direct messages
```bash
hcom open --prefix cool # Creates cool-hovoa7
hcom open --prefix cool # Creates cool-homab8
hcom send '@cool hi, you are cool'
hcom send '@homab8 hi, you are cooler'
```
### Persistent thinking mode
```bash
# Thinking mode maintains for entire session
HCOM_INITIAL_PROMPT="ultrathink and do x" hcom open
# Every new message reply uses ultrathink
```
---
<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>
| Command | Description |
|---------|-------------|
| `hcom open [n]` | Launch n Claude instances (or named agents) |
| `hcom open -p` | Launch headless process |
| `hcom open --prefix <p> [n]` | Launch with `<p>` prefix (e.g., api-hova7) |
| `hcom open --claude-args "..."` | Pass flags to Claude Code |
| `hcom watch` | Conversation/status dashboard |
| `hcom clear` | Clear and archive conversation |
| `hcom cleanup` | Safely Remove HCOM hooks from current directory while preserving your settings (`--all` for all directories) |
| `hcom kill [name]` | Kill specific instance (--all for all running instances) |
### Automation Commands
| Command | Description |
|---------|-------------|
| `hcom send 'message'` | Send message to all instances |
| `hcom send '@alias msg'` | Send to specific instances alias or prefix |
| `hcom watch --logs` | View message log history (non-interactive) |
| `hcom watch --status` | Show instance status as JSON (non-interactive) |
| `hcom watch --wait [timeout]` | Wait and notify for new messages |
</details>
<details>
<summary><strong>🗿 Examples</strong></summary>
```bash
# Instances can be privately @mentioned by alias or prefix
hcom open --prefix cool # Creates cool-hovoa7
hcom open --prefix cool # Creates cool-hovob8
hcom open --prefix notcool # creates notcool-hovoc9
# Send a targeted message in dashboard
@notcool i think you smell good
@cool that other guy is smelly
@hovoa7 im lying about the smelly thing
# Launch 3 headless instances that die after 60 seconds of inactivity
HCOM_WAIT_TIMEOUT="60" hcom open 3 -p
# Manually kill all instances
hcom kill --all
# Launch multiple of the same subagent
hcom open reviewer reviewer reviewer
# Launch agent with specific prompt
HCOM_INITIAL_PROMPT='write tests' hcom open test-writer
# Resume instance (hcom chat will continue)
hcom open --claude-args "--resume session_id"
# Text appended to all messages recieved by instance
HCOM_INSTANCE_HINTS="remember where you came from" hcom open
# Pass multiple Claude flags
hcom open orchestrator --claude-args "--model sonnet --resume session_id"
```
</details>
<details>
<summary><strong>🦖 Configuration</strong></summary>
### Configuration
Settings can be changed two ways:
#### Method 1: Environment variable (temporary, per-command/instance)
```bash
HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-but-not-great-with-updates
```
#### Method 2: Config file (persistent, affects all instances)
### Config File Location
`~/.hcom/config.json`
| Setting | Default | Environment Variable | Description |
|---------|---------|---------------------|-------------|
| `wait_timeout` | 1800 | `HCOM_WAIT_TIMEOUT` | How long instances wait for messages (seconds) |
| `max_message_size` | 1048576 | `HCOM_MAX_MESSAGE_SIZE` | Maximum message length (1MB) |
| `max_messages_per_delivery` | 50 | `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 in chat" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |
| `first_use_text` | "Essential, concise messages only" | `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 Options) |
| `cli_hints` | "" | `HCOM_CLI_HINTS` | Extra text added to CLI outputs |
| `instance_hints` | "" | `HCOM_INSTANCE_HINTS` | Extra text added to instance messages |
| `auto_watch` | true | `HCOM_AUTO_WATCH` | Auto-launch watch dashboard after open |
| `env_overrides` | {} | - | Additional environment variables for Claude Code |
### Examples
```bash
# Change your name for one command
HCOM_SENDER_NAME="coolguy" hcom send "LGTM!"
# Make instances timeout after 60 seconds instead of 30 minutes
HCOM_WAIT_TIMEOUT=60 hcom open 3
# Custom welcome message
HCOM_FIRST_USE_TEXT="Debug session for issue #123" hcom open 2
# Bigger delivery batches
HCOM_MAX_MESSAGES_PER_DELIVERY=100 hcom watch --logs
```
**Windows PowerShell**:
```powershell
# Set environment variables in PowerShell
$env:HCOM_TERMINAL_MODE="same_terminal"; hcom open agent-name
$env:HCOM_WAIT_TIMEOUT="60"; hcom open 3
$env:HCOM_INITIAL_PROMPT="go home buddy!"; hcom open
```
### 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) - Timed out/disconnected
- ○ **unknown** (gray) - No status data
- **(bg)** suffix - Instance running in background headless mode
</details>
<details>
<summary><strong>🎲 How It Works</strong></summary>
### Hooks!
hcom adds hooks to your project directory's `.claude/settings.local.json`:
1. **Sending**: Claude agents use `eval $HCOM send "message"` internally (you use `hcom send` from terminal or dashboard)
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 open researcher`, 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 open` join the chat
- **@-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.json # Configuration
└── archive/ # Archived sessions
your-project/
└── .claude/
└── settings.local.json # hcom hooks
```
</details>
<details>
<summary><strong>🥔 Terminal Options</strong></summary>
### Terminal Mode
Configure terminal behavior in `~/.hcom/config.json`:
- `"terminal_mode": "new_window"` - Opens new terminal window(s) (default)
- `"terminal_mode": "same_terminal"` - Opens in current terminal
#### Running in current terminal temporarily
```bash
# For single instances
HCOM_TERMINAL_MODE=same_terminal hcom open
```
### Default Terminals
- **macOS**: Terminal.app
- **Linux**: gnome-terminal, konsole, or xterm
- **Windows & WSL**: Windows Terminal / Git Bash
- **Android**: Termux
### Custom Terminals
Configure `terminal_command` in `~/.hcom/config.json` (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
```json
"terminal_command": "open -a iTerm {script}"
```
#### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)
```json
"terminal_command": "ttab {script}"
```
#### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)
```json
"terminal_command": "wttab {script}"
```
#### More
```json
# WezTerm Linux/Windows
"terminal_command": "wezterm start -- bash {script}"
# Tabs from within WezTerm
"terminal_command": "wezterm cli spawn -- bash {script}"
# WezTerm macOS:
"terminal_command": "open -n -a WezTerm.app --args start -- bash {script}"
# Tabs from within WezTerm macOS
"terminal_command": "/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bash {script}"
# Wave Terminal Mac/Linux/Windows. From within Wave Terminal:
"terminal_command": "wsh run -- bash {script}"
# Alacritty macOS:
"terminal_command": "open -n -a Alacritty.app --args -e bash {script}"
# Alacritty Linux:
"terminal_command": "alacritty -e bash {script}"
# Kitty macOS:
"terminal_command": "open -n -a kitty.app --args {script}"
# Kitty Linux
"terminal_command": "kitty {script}"
```
#### tmux
```json
"terminal_command": "tmux new-window -n hcom {script}"
```
```bash
# tmux commands work inside tmux, start a session with:
tmux new-session 'hcom open 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_COMMAND="tmux split-window -h {script}" hcom open 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 open`
---
</details>
<details>
<summary><strong>⚗️ Remove</strong></summary>
### Archive Conversation / Start New
```bash
hcom clear
```
### Kill Running Instances
```bash
# Kill specific instance
hcom kill hovoa7
# Kill all instances
hcom kill --all
```
### Remove HCOM hooks from current directory
```bash
hcom cleanup
```
### Remove HCOM hooks from all directories
```bash
hcom cleanup --all
```
### 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
---
Raw data
{
"_id": null,
"home_page": null,
"name": "hcom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "claude, claude-code, hooks, agents, cli, multi-agent, orchestration, terminal",
"author": "aannoo",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/48/90/033f878aabc6869619aea5438243883f5636b12d414ce9ee0422c4960ed6/hcom-0.3.1.tar.gz",
"platform": null,
"description": "# hcom - Claude Hook Comms\n\n[](https://pypi.org/project/hcom/)\n [](https://opensource.org/license/MIT) [](https://python.org) [](https://deepwiki.com/aannoo/claude-hook-comms)\n\nCLI 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.\n\n\n\n## \ud83e\udd66 Usage\n\n**Run without installing** ([uv](https://docs.astral.sh/uv/#installation))\n```bash\nuvx hcom open 2\n```\n\n**Install** (optional)\n```bash\npip install hcom\nhcom open 2\n```\n\n| Commands | |\n|---------|-------------|\n| `hcom open [n]` | Launch `n` instances or named agents |\n| `hcom watch` | View live dashboard and messaging |\n| `hcom clear` | Clear and start new conversation |\n| `hcom cleanup` | Safely remove hcom hooks, preserving your project settings |\n\n\n## \ud83e\udd86 What It Does\n\n`hcom open` adds hooks to the `.claude/settings.local.json` file in the current folder 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.\n\n### Subagents in their own terminal\n```bash\n# Launch subagents from your .claude/agents\nhcom open planner code-writer reviewer\n```\n\n### Persistent headless instances\n```bash\n# Launch one headless instance (default 30min timeout)\nhcom open -p\n```\n\n### Groups and direct messages\n```bash\nhcom open --prefix cool # Creates cool-hovoa7\nhcom open --prefix cool # Creates cool-homab8\nhcom send '@cool hi, you are cool'\nhcom send '@homab8 hi, you are cooler'\n```\n\n### Persistent thinking mode\n```bash\n# Thinking mode maintains for entire session\nHCOM_INITIAL_PROMPT=\"ultrathink and do x\" hcom open\n# Every new message reply uses ultrathink\n```\n\n---\n\n\n<details>\n<summary><strong>\ud83e\uddb7 Features</strong></summary>\n\n- **Multi-Terminal Launch** - Launch Claude Code subagents in new terminals\n- **Background Mode** - Run headless instances without terminal windows\n- **Interactive subagents** - Run subagents in their own terminal window\n- **Live Dashboard** - Real-time monitoring and messaging\n- **Multi-Agent Communication** - Instances talk to each other via shared chat\n- **@Mention Targeting** - Send messages to specific instances or teams\n- **Session Persistence** - Resume previous conversations automatically\n- **Zero Dependencies** - Pure Python stdlib, works everywhere\n- **Cross-platform** - Native support for Windows, WSL, macOS, Linux, Android\n\n</details>\n\n<details>\n<summary><strong>\ud83e\udd68 All Commands</strong></summary>\n\n\n| Command | Description |\n|---------|-------------|\n| `hcom open [n]` | Launch n Claude instances (or named agents) |\n| `hcom open -p` | Launch headless process |\n| `hcom open --prefix <p> [n]` | Launch with `<p>` prefix (e.g., api-hova7) |\n| `hcom open --claude-args \"...\"` | Pass flags to Claude Code |\n| `hcom watch` | Conversation/status dashboard |\n| `hcom clear` | Clear and archive conversation |\n| `hcom cleanup` | Safely Remove HCOM hooks from current directory while preserving your settings (`--all` for all directories) |\n| `hcom kill [name]` | Kill specific instance (--all for all running instances) |\n\n### Automation Commands\n| Command | Description |\n|---------|-------------|\n| `hcom send 'message'` | Send message to all instances |\n| `hcom send '@alias msg'` | Send to specific instances alias or prefix |\n| `hcom watch --logs` | View message log history (non-interactive) |\n| `hcom watch --status` | Show instance status as JSON (non-interactive) |\n| `hcom watch --wait [timeout]` | Wait and notify for new messages |\n\n</details>\n\n\n\n<details>\n<summary><strong>\ud83d\uddff Examples</strong></summary>\n\n```bash\n# Instances can be privately @mentioned by alias or prefix\nhcom open --prefix cool # Creates cool-hovoa7\nhcom open --prefix cool # Creates cool-hovob8\nhcom open --prefix notcool # creates notcool-hovoc9\n\n# Send a targeted message in dashboard\n@notcool i think you smell good\n@cool that other guy is smelly\n@hovoa7 im lying about the smelly thing\n\n# Launch 3 headless instances that die after 60 seconds of inactivity\nHCOM_WAIT_TIMEOUT=\"60\" hcom open 3 -p\n# Manually kill all instances\nhcom kill --all\n\n# Launch multiple of the same subagent\nhcom open reviewer reviewer reviewer\n\n# Launch agent with specific prompt\nHCOM_INITIAL_PROMPT='write tests' hcom open test-writer\n\n# Resume instance (hcom chat will continue)\nhcom open --claude-args \"--resume session_id\"\n\n# Text appended to all messages recieved by instance\nHCOM_INSTANCE_HINTS=\"remember where you came from\" hcom open\n\n# Pass multiple Claude flags\nhcom open orchestrator --claude-args \"--model sonnet --resume session_id\"\n```\n\n</details>\n\n<details>\n<summary><strong>\ud83e\udd96 Configuration</strong></summary>\n\n### Configuration\n\nSettings can be changed two ways:\n\n#### Method 1: Environment variable (temporary, per-command/instance)\n\n\n```bash\nHCOM_INSTANCE_HINTS=\"always update chat with progress\" hcom open nice-subagent-but-not-great-with-updates\n```\n\n#### Method 2: Config file (persistent, affects all instances)\n\n### Config File Location\n\n`~/.hcom/config.json`\n\n| Setting | Default | Environment Variable | Description |\n|---------|---------|---------------------|-------------|\n| `wait_timeout` | 1800 | `HCOM_WAIT_TIMEOUT` | How long instances wait for messages (seconds) |\n| `max_message_size` | 1048576 | `HCOM_MAX_MESSAGE_SIZE` | Maximum message length (1MB) |\n| `max_messages_per_delivery` | 50 | `HCOM_MAX_MESSAGES_PER_DELIVERY` | Messages delivered per batch |\n| `sender_name` | \"bigboss\" | `HCOM_SENDER_NAME` | Your name in chat |\n| `sender_emoji` | \"\ud83d\udc33\" | `HCOM_SENDER_EMOJI` | Your emoji icon |\n| `initial_prompt` | \"Say hi in chat\" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |\n| `first_use_text` | \"Essential, concise messages only\" | `HCOM_FIRST_USE_TEXT` | Welcome message for instances |\n| `terminal_mode` | \"new_window\" | `HCOM_TERMINAL_MODE` | How to launch terminals (\"new_window\", \"same_terminal\", \"show_commands\") |\n| `terminal_command` | null | `HCOM_TERMINAL_COMMAND` | Custom terminal command (see Terminal Options) |\n| `cli_hints` | \"\" | `HCOM_CLI_HINTS` | Extra text added to CLI outputs |\n| `instance_hints` | \"\" | `HCOM_INSTANCE_HINTS` | Extra text added to instance messages |\n| `auto_watch` | true | `HCOM_AUTO_WATCH` | Auto-launch watch dashboard after open |\n| `env_overrides` | {} | - | Additional environment variables for Claude Code |\n\n### Examples\n\n```bash\n# Change your name for one command\nHCOM_SENDER_NAME=\"coolguy\" hcom send \"LGTM!\"\n\n# Make instances timeout after 60 seconds instead of 30 minutes\nHCOM_WAIT_TIMEOUT=60 hcom open 3\n\n# Custom welcome message\nHCOM_FIRST_USE_TEXT=\"Debug session for issue #123\" hcom open 2\n\n# Bigger delivery batches\nHCOM_MAX_MESSAGES_PER_DELIVERY=100 hcom watch --logs\n```\n\n**Windows PowerShell**:\n```powershell\n# Set environment variables in PowerShell\n$env:HCOM_TERMINAL_MODE=\"same_terminal\"; hcom open agent-name\n$env:HCOM_WAIT_TIMEOUT=\"60\"; hcom open 3\n$env:HCOM_INITIAL_PROMPT=\"go home buddy!\"; hcom open\n```\n\n### Status Indicators\n\nWhen running `hcom watch`, each instance shows its current state:\n\n- \u25b6 **active** (green) - Working (processing/executing)\n- \u25b7 **delivered** (cyan) - Just received a message\n- \u25c9 **waiting** (blue) - Waiting for messages\n- \u25a0 **blocked** (yellow) - Permission request pending\n- \u25cb **inactive** (red) - Timed out/disconnected\n- \u25cb **unknown** (gray) - No status data\n- **(bg)** suffix - Instance running in background headless mode\n\n</details>\n\n<details>\n<summary><strong>\ud83c\udfb2 How It Works</strong></summary>\n\n### Hooks!\n\nhcom adds hooks to your project directory's `.claude/settings.local.json`:\n\n1. **Sending**: Claude agents use `eval $HCOM send \"message\"` internally (you use `hcom send` from terminal or dashboard)\n2. **Receiving**: Other Claudes get notified via Stop hook or immediate delivery after sending\n3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages\n\n- **Identity**: Each instance gets a unique name based on session ID (e.g., \"hovoa7\")\n- **Persistence**: Names persist across `--resume` maintaining conversation context\n- **Status Detection**: Notification hook tracks permission requests and activity\n- **Agents**: When you run `hcom open researcher`, 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\n\n### Architecture\n- **Single conversation** - All instances share one global conversation\n- **Opt-in participation** - Only Claude Code instances launched with `hcom open` join the chat\n- **@-mention filtering** - Target messages to specific instances or teams\n\n### File Structure\n```plaintext\n~/.hcom/ \n\u251c\u2500\u2500 hcom.log # Conversation log\n\u251c\u2500\u2500 instances/ # Instance tracking\n\u251c\u2500\u2500 logs/ # Background process logs\n\u251c\u2500\u2500 config.json # Configuration\n\u2514\u2500\u2500 archive/ # Archived sessions\n\nyour-project/ \n\u2514\u2500\u2500 .claude/\n \u2514\u2500\u2500 settings.local.json # hcom hooks\n```\n\n</details>\n\n\n<details>\n<summary><strong>\ud83e\udd54 Terminal Options</strong></summary>\n\n### Terminal Mode\n\nConfigure terminal behavior in `~/.hcom/config.json`:\n- `\"terminal_mode\": \"new_window\"` - Opens new terminal window(s) (default)\n- `\"terminal_mode\": \"same_terminal\"` - Opens in current terminal\n\n#### Running in current terminal temporarily\n```bash\n# For single instances\nHCOM_TERMINAL_MODE=same_terminal hcom open\n```\n\n### Default Terminals\n\n- **macOS**: Terminal.app\n- **Linux**: gnome-terminal, konsole, or xterm\n- **Windows & WSL**: Windows Terminal / Git Bash\n- **Android**: Termux\n\n\n### Custom Terminals\n\nConfigure `terminal_command` in `~/.hcom/config.json` (permanent) or environment variables (temporary).\n\n#### How to use this\n\nThe `{script}` placeholder is replaced by HCOM with the path to a temporary bash script that launches Claude Code.\n\nYour custom command just needs to:\n1. Accept `{script}` as a placeholder that will be replaced with a script path\n2. Execute that script with bash\n\nExample template: `your_terminal_command --execute \"bash {script}\"`\n\n### Custom Terminal Examples\n\n#### iTerm2\n```json\n\"terminal_command\": \"open -a iTerm {script}\"\n```\n\n#### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)\n```json\n\"terminal_command\": \"ttab {script}\"\n```\n\n#### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)\n```json\n\"terminal_command\": \"wttab {script}\"\n```\n\n#### More\n```json\n# WezTerm Linux/Windows\n\"terminal_command\": \"wezterm start -- bash {script}\"\n\n# Tabs from within WezTerm\n\"terminal_command\": \"wezterm cli spawn -- bash {script}\"\n\n# WezTerm macOS:\n\"terminal_command\": \"open -n -a WezTerm.app --args start -- bash {script}\"\n\n# Tabs from within WezTerm macOS\n\"terminal_command\": \"/Applications/WezTerm.app/Contents/MacOS/wezterm cli spawn -- bash {script}\"\n\n# Wave Terminal Mac/Linux/Windows. From within Wave Terminal:\n\"terminal_command\": \"wsh run -- bash {script}\"\n\n# Alacritty macOS:\n\"terminal_command\": \"open -n -a Alacritty.app --args -e bash {script}\"\n\n# Alacritty Linux:\n\"terminal_command\": \"alacritty -e bash {script}\"\n\n# Kitty macOS:\n\"terminal_command\": \"open -n -a kitty.app --args {script}\"\n\n# Kitty Linux\n\"terminal_command\": \"kitty {script}\"\n```\n\n#### tmux\n```json\n\"terminal_command\": \"tmux new-window -n hcom {script}\"\n```\n```bash\n# tmux commands work inside tmux, start a session with:\ntmux new-session 'hcom open 3' # each instance opens in new tmux window\n\n# Or one time split-panes:\n# Start tmux with split panes and 3 claude instances in hcom chat\nHCOM_TERMINAL_COMMAND=\"tmux split-window -h {script}\" hcom open 3\n```\n\n### Android (Termux)\n\n1. Install [Termux](https://f-droid.org/packages/com.termux/) from F-Droid (not Google Play)\n2. Setup:\n ```bash\n pkg install python nodejs\n npm install -g @anthropic-ai/claude-cli\n pip install hcom\n ```\n3. Enable:\n ```bash\n echo \"allow-external-apps=true\" >> ~/.termux/termux.properties\n termux-reload-settings\n ```\n4. Enable: \"Display over other apps\" permission for visible terminals\n\n5. Run: `hcom open`\n\n---\n\n</details>\n\n\n<details>\n<summary><strong>\u2697\ufe0f Remove</strong></summary>\n\n\n### Archive Conversation / Start New\n```bash\nhcom clear\n```\n\n### Kill Running Instances\n```bash\n# Kill specific instance\nhcom kill hovoa7\n\n# Kill all instances\nhcom kill --all\n```\n\n### Remove HCOM hooks from current directory\n```bash\nhcom cleanup\n```\n\n### Remove HCOM hooks from all directories\n```bash\nhcom cleanup --all\n```\n\n### Remove hcom Completely\n1. Remove hcom: `rm /usr/local/bin/hcom` (or wherever you installed hcom)\n2. Remove all data: `rm -rf ~/.hcom`\n\n</details>\n\n## \ud83e\udd90 Requirements\n\n- Python 3.10+\n- [Claude Code](https://claude.ai/code)\n\n\n\n## \ud83c\udf2e License\n\n- MIT License\n\n---\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://github.com/aannoo/claude-hook-comms#readme",
"Homepage": "https://github.com/aannoo/claude-hook-comms",
"Issues": "https://github.com/aannoo/claude-hook-comms/issues",
"Repository": "https://github.com/aannoo/claude-hook-comms"
},
"split_keywords": [
"claude",
" claude-code",
" hooks",
" agents",
" cli",
" multi-agent",
" orchestration",
" terminal"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5c0a2659c1a428f20be637d5c23f196753c7dd8b695c0ddee7024741e53b5a00",
"md5": "3beb9346d605eba2f0260c7014178792",
"sha256": "c5351a7f8fdec3124ca0344ec161ceed6f592abdaf18600dad3905f7033fe432"
},
"downloads": -1,
"filename": "hcom-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3beb9346d605eba2f0260c7014178792",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 40556,
"upload_time": "2025-10-06T04:30:24",
"upload_time_iso_8601": "2025-10-06T04:30:24.181821Z",
"url": "https://files.pythonhosted.org/packages/5c/0a/2659c1a428f20be637d5c23f196753c7dd8b695c0ddee7024741e53b5a00/hcom-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4890033f878aabc6869619aea5438243883f5636b12d414ce9ee0422c4960ed6",
"md5": "6720645166488185f74bc8ffa7e11762",
"sha256": "21844af203f64e145f06c47c48ec173c91c5d371ba9c42cfd848ebe0dd9897f8"
},
"downloads": -1,
"filename": "hcom-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "6720645166488185f74bc8ffa7e11762",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 46853,
"upload_time": "2025-10-06T04:30:25",
"upload_time_iso_8601": "2025-10-06T04:30:25.814262Z",
"url": "https://files.pythonhosted.org/packages/48/90/033f878aabc6869619aea5438243883f5636b12d414ce9ee0422c4960ed6/hcom-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 04:30:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aannoo",
"github_project": "claude-hook-comms#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hcom"
}
