hcom 0.1.0__tar.gz → 0.1.2__tar.gz

hcom-0.1.2/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include pyproject.toml
+recursive-include src/hcom *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+prune tests
+prune docs
+prune old
+prune shite
+prune examples
+prune requirements
+prune test_results
+prune hcom-older-stuff

{hcom-0.1.0 → hcom-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using hooks
 Author-email: aannoo <your@email.com>
 License: MIT
@@ -28,94 +28,92 @@ Description-Content-Type: text/markdown
 
 # Claude Code Hook Comms
 
-Lightweight CLI tool for real-time messaging between Claude Code instances/subagents using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
+Lightweight CLI tool for real-time communication between claude code [subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
 
 ## 🦆 What It Does
 
 Creates a group chat where you and multiple interactive Claude Code subagents can communicate with each other across different folders on your computer. Works on Mac, Linux, and Windows with zero dependencies.
 
-![Claude Hook Comms Example](screenshot.jpg)
+![Claude Hook Comms Example](https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/screenshot.jpg)
 
-## 🦷 Key Features
+## 🦷 Features
 
-- **New Window** - Claude subagents open in new terminals
+- **Multi-Terminal Launch** - Launch claude code subagents in new terminals
+- **Live Dashboard** - Real-time monitoring of all instances
 - **Multi-Agent Communication** - Claude instances talk to each other across projects
 - **@Mention Targeting** - Send messages to specific subagents or teams
-- **Live Dashboard** - Real-time monitoring of all instances
 - **Zero Dependencies** - Pure Python stdlib, works everywhere
 
 ## 🎪 Quick Start
 
-### Download
+### Use Without Installing
 ```bash
-curl -sL https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py | sudo tee /usr/local/bin/hcom > /dev/null && sudo chmod +x /usr/local/bin/hcom
-```
-
-<details>
-<summary><strong>🦑 Windows</strong></summary>
+# Launch 3 default Claude instances connected to group chat
+uvx hcom open 3
 
-```powershell
-# Download Python file
-Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/hcom.py" -OutFile "hcom.py"
+# Launch researcher and code-writer from your .claude/agents
+uvx hcom open researcher code-writer
 
-# Run python file directly
-python path/to/hcom.py open 2
+# View/send messages in dashboard
+uvx hcom watch
 ```
-</details>
 
-### Usage
+### Install
+
 ```bash
-# 1. Launch 3 Claude instances connected to group chat
+# uv
+uv tool install hcom
+# or pip
+pip install hcom
+# then use with:
 hcom open 3
-
-# 2. View/send messages in dashboard
-hcom watch
 ```
 
 
+## 🦐 Requirements
 
-### Launch Claude Code Agents
-```bash
-# Launch researcher and code-writer from your .claude/agents
-hcom open researcher code-writer
+- Python 3.6+
+- [Claude Code](https://claude.ai/code)
 
-# Launch backend-coder frontend-coder orchestrator tester from your .claude/agents
-hcom open backend-coder frontend-coder orchestrator tester
-```
 
-### Launch Headless Mode
+## 🗿 More Examples
+
 ```bash
-# Launch researcher and code-writer from your .claude/agents and work in background
-hcom open researcher code-writer --claude-args "-p"
+# Launch 2 generic instances + 2 specific agents
+hcom open 2 backend-coder frontend-coder
 
-# Launch reviewer in headless mode with a prompt
-hcom open --claude-args "-p 'review git code changes when you get notified'"
-```
+# Launch multiple of the same agent
+hcom open reviewer reviewer reviewer  # 3 separate reviewers
 
-### Launch with Options
-```bash
-# Launch researcher and code-writer from your .claude/agents and work in background
-hcom open researcher code-writer --prefix 'greenteam'
-hcom send '@greenteam get to work on green stuff'
+# Launch agents in background with specific prompts
+hcom open test-writer --claude-args "-p 'write tests for any new code'"
 
-# Launch 2 claude code instances and 2 of your agents
-hcom open 2 backend-coder frontend-coder
-```
+# Launch watchers that respond to notifications
+hcom open reviewer --claude-args "-p 'review when @mentioned'"
 
+# Pass multiple Claude flags
+hcom open orchestrator --claude-args "--model claude-3-opus 
+--resume session_id"
 
-## 🦐 Requirements
+# Launch in specific directories
+cd backend && hcom open api-specialist
+cd ../frontend && hcom open ui-specialist
 
-- Python 3.6+
-- [Claude Code](https://claude.ai/code)
+# Create named teams that can be @mentioned
+cd ~/api && hcom open --prefix api debugger
+cd ~/auth && hcom open --prefix auth debugger
+
+# Message specific teams
+hcom send "@api login works but API fails" # or in dashboard: hcom watch
+```
 
 
 ## 🥨 Commands
 
-### Commands
 | Command | Description |
 |---------|-------------|
 | `hcom open [n]` | Launch n Claude instances (or named agents) |
-| `hcom watch` | View conversation/status dashboard |
+| `hcom watch` | Conversation/status dashboard |
 | `hcom clear` | Clear and archive conversation |
 | `hcom cleanup` | Remove HCOM hooks from current directory |
 
@@ -125,7 +123,7 @@ hcom open 2 backend-coder frontend-coder
 | `hcom send 'message'` | Send message |
 | `hcom watch --logs` | View message history (non-interactive) |
 | `hcom watch --status` | Show instance status (non-interactive) |
-| `hcom watch --wait[=seconds]` | Wait for new messages (automation) |
+| `hcom watch --wait [timeout]` | Wait and notify for new messages |
 
 ---
 
@@ -136,15 +134,14 @@ hcom open 2 backend-coder frontend-coder
 
 Settings can be changed two ways:
 
+#### Method 1: Environment variable (temporary, per-command/instance)
+
+
 ```bash
-# Method 1: Environment variable (termporary per-command/instance)
 HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-but-not-great-with-updates
-
-# Method 2: Config file (affects all instances)
-# Edit ~/.hcom/config.json
 ```
 
-### All Settings
+#### Method 2: Config file (persistent, affects all instances)
 
 ### Config File Location
 
@@ -158,12 +155,12 @@ HCOM_INSTANCE_HINTS="always update chat with progress" hcom open nice-subagent-b
 | `sender_name` | "bigboss" | `HCOM_SENDER_NAME` | Your name in chat |
 | `sender_emoji` | "🐳" | `HCOM_SENDER_EMOJI` | Your emoji icon |
 | `initial_prompt` | "Say hi" | `HCOM_INITIAL_PROMPT` | What new instances are told to do |
-| `first_use_text` | "Essential, concise messages only. Say hi in hcom chat" | `HCOM_FIRST_USE_TEXT` | Welcome message for instances |
+| `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 Integration) |
+| `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 |
-| `env_overrides` | {} | - | Additional environment variables for Claude |
+| `env_overrides` | {} | - | Additional environment variables for Claude Code |
 
 ### Examples
 
@@ -203,12 +200,13 @@ hcom adds hooks to your project directory's `.claude/settings.local.json`:
 3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages
 
 - **Identity**: Each instance gets a unique name based on conversation UUID (e.g., "hovoa7")
-- **Persistence**: Names persist across `claude --resume` maintaining conversation context
+- **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)
 
 ### Architecture
 - **Single conversation** - All instances share one global conversation
-- **Opt-in participation** - Only instances launched with `hcom open` join the chat
+- **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
@@ -227,115 +225,79 @@ your-project/
 
 
 <details>
-<summary><strong>🧈 Launching Claude Code</strong></summary>
-
-### Launching Claude Code
+<summary><strong>🥔 Terminal Options</strong></summary>
 
-Use `hcom open` to automatically launch Claude instances with proper setup:
-
-```bash
-# Launch 3 generic instances
-hcom open 3
-
-# Launch with custom terminal mode
-hcom open 2  # Uses terminal_mode from config
-
-# Launch named agents
-hcom open writer researcher
-```
+### Terminal Mode
 
 Configure terminal behavior in `~/.hcom/config.json`:
 - `"terminal_mode": "new_window"` - Opens new terminal windows (default)
-- `"terminal_mode": "same_terminal"` - Runs in background
+- `"terminal_mode": "same_terminal"` - Opens in current terminal
 - `"terminal_mode": "show_commands"` - Prints commands without executing
 
+### Default Terminals
+
+- **macOS**: Terminal.app
+- **Linux**: gnome-terminal, konsole, or xterm
+- **Windows**: Windows Terminal / PowerShell
+
 ### Running in Current Terminal
 ```bash
-# For single instance work
+# For single instances
 HCOM_TERMINAL_MODE=same_terminal hcom open
-# This runs Claude directly in your current terminal
 ```
 
-</details>
-
-<details>
-<summary><strong>🥔 Integrations</strong></summary>
-
-### Custom Terminal Integration
+### Custom Terminal Examples
 
 Configure `terminal_command` in `~/.hcom/config.json` to use your preferred terminal:
 
 ### iTerm2
 ```json
 {
-  "terminal_command": "osascript -e 'tell app \"iTerm\" to create window with default profile command \"{env} {cmd}\"'"
+  "terminal_command": "osascript -e 'tell app \"iTerm2\" to create window with default profile' -e 'tell current session of current window to write text \"{env} {cmd}\"'"
 }
 ```
 
 ### Alacritty
 ```json
 {
-  "terminal_command": "alacritty -e bash -c '{env} {cmd}'"
-}
-```
-
-### Windows Terminal
-```json
-{
-  "terminal_command": "wt new-tab cmd /k \"{env} & {cmd}\""
+  "terminal_command": "alacritty -e sh -c '{env} {cmd}'"
 }
 ```
 
 ### Kitty
 ```json
 {
-  "terminal_command": "kitty -e bash -c '{env} {cmd}'"
+  "terminal_command": "kitty sh -c '{env} {cmd}'"
 }
 ```
 
-### tmux
+### WezTerm
 ```json
 {
-  "terminal_command": "tmux new-window -n hcom '{env} {cmd}'"
+  "terminal_command": "wezterm cli spawn --new-window -- sh -c '{env} {cmd}'"
 }
 ```
 
-### screen
+### tmux
 ```json
 {
-  "terminal_command": "screen -dmS hcom-$$ bash -c '{env} {cmd}'"
+  "terminal_command": "tmux new-window -n hcom sh -c '{env} {cmd}'"
 }
 ```
 
 ### Available Placeholders
 - `{cmd}` - The claude command to execute
-- `{env}` - Environment variables (pre-formatted)
+- `{env}` - Environment variables (pre-formatted as `VAR1='value1' VAR2='value2'`)
 - `{cwd}` - Current working directory
 
-</details>
-
-<details>
-<summary><strong>🥚 Troubleshooting</strong></summary>
-
-### Common Issues
-
-- **Claude stops responding**: Default idle timeout is 10 minutes (configure via `wait_timeout`)
-- **Message truncated**: Message size limit is 4096 chars (configure via `max_message_size`)
-
-### Debug Commands
-```bash
-# Run Claude in debug mode to see hook execution
-hcom open --claude-args "--debug"
+### Notes
+- Custom commands must exit with code 0 for success
+- The `{env}` placeholder contains shell-quoted environment variables
+- Most terminals require wrapping the command in `sh -c` to handle environment variables correctly
 
-# View conversation log
-tail -f ~/.hcom/hcom.log
-
-# Check instance status
-cat ~/.hcom/hcom.json
-
-```
 </details>
 
+
 <details>
 <summary><strong>🦆 Remove</strong></summary>
 
@@ -345,9 +307,14 @@ cat ~/.hcom/hcom.json
 hcom clear
 ```
 
-### Remove all HCOM hooks
+### Remove HCOM hooks from current directory
+```bash
+hcom cleanup
+```
+
+### Remove HCOM hooks from all directories
 ```bash
-hcom clenup --all
+hcom cleanup --all
 ```
 
 ### Remove hcom Completely