hcom 0.1.6__tar.gz → 0.1.8__tar.gz

{hcom-0.1.6/src/hcom.egg-info → hcom-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.1.6
+Version: 0.1.8
 Summary: Lightweight CLI tool for real-time communication between Claude Code subagents using hooks
 Author-email: aannoo <your@email.com>
 License: MIT
@@ -92,7 +92,7 @@ hcom open test-writer --claude-args "-p 'write tests for any new code'"
 hcom open reviewer --claude-args "-p 'review when @mentioned'"
 
 # Pass multiple Claude flags
-hcom open orchestrator --claude-args "--model claude-3-opus 
+hcom open orchestrator --claude-args "--model sonnet 
 --resume session_id"
 
 # Launch in specific directories
@@ -100,11 +100,12 @@ cd backend && hcom open api-specialist
 cd ../frontend && hcom open ui-specialist
 
 # Create named teams that can be @mentioned
-cd ~/api && hcom open --prefix api debugger
-cd ~/auth && hcom open --prefix auth debugger
+cd ~/api && hcom open --prefix api debugger  # Creates api-hovoa7
+cd ~/auth && hcom open --prefix auth debugger  # Creates auth-hovob8
 
-# Message specific teams
-hcom send "@api login works but API fails" # or in dashboard: hcom watch
+# Message specific teams or instances
+hcom send "@api login works but API fails"  # Messages all api-* instances
+hcom send "@hovoa7 can you check this?"     # Message specific instance by name
 ```
 
 
@@ -120,7 +121,7 @@ hcom send "@api login works but API fails" # or in dashboard: hcom watch
 ### Automation Commands
 | Command | Description |
 |---------|-------------|
-| `hcom send 'message'` | Send message |
+| `hcom send 'message'` | Send message to chat |
 | `hcom watch --logs` | View message history (non-interactive) |
 | `hcom watch --status` | Show instance status (non-interactive) |
 | `hcom watch --wait [timeout]` | Wait and notify for new messages |
@@ -195,7 +196,7 @@ HCOM_MAX_MESSAGE_SIZE=8192 hcom send "$(cat long_report.txt)"
 
 hcom adds hooks to your project directory's `.claude/settings.local.json`:
 
-1. **Sending**: Claude writes messages with `echo "HCOM_SEND:message"` - captured by PostToolUse hook
+1. **Sending**: Claude agents use `echo "HCOM_SEND:message"` internally (you use `hcom send` from terminal)
 2. **Receiving**: Other Claudes get notified via Stop hook
 3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages
 

{hcom-0.1.6 → hcom-0.1.8}/README.md

@@ -64,7 +64,7 @@ hcom open test-writer --claude-args "-p 'write tests for any new code'"
 hcom open reviewer --claude-args "-p 'review when @mentioned'"
 
 # Pass multiple Claude flags
-hcom open orchestrator --claude-args "--model claude-3-opus 
+hcom open orchestrator --claude-args "--model sonnet 
 --resume session_id"
 
 # Launch in specific directories
@@ -72,11 +72,12 @@ cd backend && hcom open api-specialist
 cd ../frontend && hcom open ui-specialist
 
 # Create named teams that can be @mentioned
-cd ~/api && hcom open --prefix api debugger
-cd ~/auth && hcom open --prefix auth debugger
+cd ~/api && hcom open --prefix api debugger  # Creates api-hovoa7
+cd ~/auth && hcom open --prefix auth debugger  # Creates auth-hovob8
 
-# Message specific teams
-hcom send "@api login works but API fails" # or in dashboard: hcom watch
+# Message specific teams or instances
+hcom send "@api login works but API fails"  # Messages all api-* instances
+hcom send "@hovoa7 can you check this?"     # Message specific instance by name
 ```
 
 
@@ -92,7 +93,7 @@ hcom send "@api login works but API fails" # or in dashboard: hcom watch
 ### Automation Commands
 | Command | Description |
 |---------|-------------|
-| `hcom send 'message'` | Send message |
+| `hcom send 'message'` | Send message to chat |
 | `hcom watch --logs` | View message history (non-interactive) |
 | `hcom watch --status` | Show instance status (non-interactive) |
 | `hcom watch --wait [timeout]` | Wait and notify for new messages |
@@ -167,7 +168,7 @@ HCOM_MAX_MESSAGE_SIZE=8192 hcom send "$(cat long_report.txt)"
 
 hcom adds hooks to your project directory's `.claude/settings.local.json`:
 
-1. **Sending**: Claude writes messages with `echo "HCOM_SEND:message"` - captured by PostToolUse hook
+1. **Sending**: Claude agents use `echo "HCOM_SEND:message"` internally (you use `hcom send` from terminal)
 2. **Receiving**: Other Claudes get notified via Stop hook
 3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages
 

{hcom-0.1.6 → hcom-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hcom"
-version = "0.1.6"
+version = "0.1.8"
 description = "Lightweight CLI tool for real-time communication between Claude Code subagents using hooks"
 readme = "README.md"
 requires-python = ">=3.6"

{hcom-0.1.6 → hcom-0.1.8}/src/hcom/__init__.py

@@ -1,3 +1,3 @@
 """Claude Hook Comms - Real-time messaging between Claude Code agents."""
 
-__version__ = "0.1.5"
+__version__ = "0.1.8"

{hcom-0.1.6 → hcom-0.1.8}/src/hcom/__main__.py

@@ -262,7 +262,7 @@ def send_message(from_instance, message):
     except Exception:
         return False
 
-def should_deliver_message(msg, instance_name):
+def should_deliver_message(msg, instance_name, all_instance_names=None):
     """Check if message should be delivered based on @-mentions"""
     text = msg['message']
     
@@ -274,11 +274,22 @@ def should_deliver_message(msg, instance_name):
     if not mentions:
         return True
     
-    for mention in mentions:
-        if instance_name.lower().startswith(mention.lower()):
-            return True
+    # Check if this instance matches any mention
+    this_instance_matches = any(instance_name.lower().startswith(mention.lower()) for mention in mentions)
+    
+    if this_instance_matches:
+        return True
+    
+    # If we have all_instance_names, check if ANY mention matches ANY instance
+    if all_instance_names:
+        any_mention_matches = any(
+            any(name.lower().startswith(mention.lower()) for name in all_instance_names)
+            for mention in mentions
+        )
+        if not any_mention_matches:
+            return True  # No matches anywhere = broadcast to all
     
-    return False
+    return False  # This instance doesn't match, but others might
 
 # ==================== Parsing and Helper Functions ====================
 
@@ -713,7 +724,7 @@ def setup_hooks():
     if 'hooks' not in settings:
         settings['hooks'] = {}
     
-    hcom_send_permission = 'Bash(echo "HCOM_SEND:*")'
+    hcom_send_permission = 'Bash(echo HCOM_SEND:*)'
     if hcom_send_permission not in settings['permissions']['allow']:
         settings['permissions']['allow'].append(hcom_send_permission)
     
@@ -885,10 +896,11 @@ def get_new_messages(instance_name):
     # Filter messages:
     # 1. Exclude own messages
     # 2. Apply @-mention filtering
+    all_instance_names = list(positions.keys())
     messages = []
     for msg in all_messages:
         if msg['from'] != instance_name:
-            if should_deliver_message(msg, instance_name):
+            if should_deliver_message(msg, instance_name, all_instance_names):
                 messages.append(msg)
     
     # Update position to end of file
@@ -1280,22 +1292,73 @@ def show_main_screen_header():
 
 def cmd_help():
     """Show help text"""
+    # Basic help for interactive users
     print("""hcom - Claude Hook Comms
 
 Usage:
   hcom open [n]                Launch n Claude instances
-  hcom open --prefix name n    Launch with name prefix
+  hcom open <agent>            Launch named agent from .claude/agents/
+  hcom open --prefix <team> n  Launch n instances with team prefix
   hcom watch                   View conversation dashboard
-  hcom clear                 Clear and archive conversation
-  hcom cleanup               Remove hooks from current directory
-  hcom cleanup --all         Remove hooks from all tracked directories
-  hcom help                  Show this help
+  hcom clear                   Clear and archive conversation
+  hcom cleanup                 Remove hooks from current directory
+  hcom cleanup --all           Remove hooks from all tracked directories
+  hcom help                    Show this help
 
 Automation:
-  hcom send 'msg'            Send message
-  hcom send '@prefix msg'    Send to specific instances
-  hcom watch --logs          Show logs
-  hcom watch --status        Show status""")
+  hcom send 'msg'              Send message to all
+  hcom send '@prefix msg'      Send to specific instances
+  hcom watch --logs            Show logs
+  hcom watch --status          Show status
+  hcom watch --wait [timeout]  Wait and notify for new messages (seconds)
+
+Docs: https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/README.md""")
+    
+    # Additional help for AI assistants when running in non-interactive mode
+    if not sys.stdin.isatty():
+        print("""
+
+=== ADDITIONAL INFO ===
+
+CONCEPT: HCOM creates multi-agent collaboration by launching multiple Claude Code 
+instances in separate terminals that share a single conversation.
+
+KEY UNDERSTANDING:
+• Single conversation - All instances share ~/.hcom/hcom.log
+• Agents are system prompts - "reviewer" loads .claude/agents/reviewer.md
+• CLI usage - Use 'hcom send' for messaging. Internal instances use 'echo HCOM_SEND:'
+• hcom open is directory-specific - always cd to project directory first              
+
+LAUNCH PATTERNS:
+  hcom open 2 reviewer                   # 2 generic + 1 reviewer agent
+  hcom open reviewer reviewer            # 2 separate reviewer instances  
+  hcom open --prefix api 2               # Team naming: api-hova7, api-kolec
+  hcom open test --claude-args "-p 'write tests'"  # Pass 'claude' CLI flags
+
+@MENTION TARGETING:
+  hcom send "message"           # Broadcasts to everyone
+  hcom send "@api fix this"     # Targets all api-* instances (api-hova7, api-kolec)
+  hcom send "@hova7 status?"    # Targets specific instance
+  (Unmatched @mentions broadcast to everyone)
+
+STATUS INDICATORS:
+• ◉ thinking, ▷ responding, ▶ executing - instance is working
+• ◉ waiting - instance is waiting for new messages (hcom send)
+• ■ blocked - instance is blocked by permission request (needs user approval)
+• ○ inactive - instance is inactive (timed out, disconnected, etc)
+              
+CONFIG:
+Environment overrides (temporary): HCOM_INSTANCE_HINTS="useful info" hcom send "hi"
+Config file (persistent): ~/.hcom/config.json
+
+Key settings (all in config.json):
+  terminal_mode: "new_window" | "same_terminal" | "show_commands"
+  initial_prompt: "Say hi in chat", first_use_text: "Essential, concise messages only..."
+  instance_hints: "", cli_hints: ""  # Extra info for instances/CLI
+
+EXPECT: Instance names are auto-generated (5-char format based on uuid: "hova7"). Check actual names 
+with 'hcom watch --status'. Instances respond automatically in shared chat.""")
+    
     return 0
 
 def cmd_open(*args):
@@ -1783,6 +1846,19 @@ def cmd_send(message):
         print(f"Error: {error}", file=sys.stderr)
         return 1
     
+    # Check for unmatched mentions (minimal warning)
+    mentions = MENTION_PATTERN.findall(message)
+    if mentions and pos_file.exists():
+        try:
+            positions = load_positions(pos_file)
+            all_instances = list(positions.keys())
+            unmatched = [m for m in mentions 
+                        if not any(name.lower().startswith(m.lower()) for name in all_instances)]
+            if unmatched:
+                print(f"Note: @{', @'.join(unmatched)} don't match any instances - broadcasting to all")
+        except Exception:
+            pass  # Don't fail on warning
+    
     # Send message
     sender_name = get_config_value('sender_name', 'bigboss')
     

{hcom-0.1.6 → hcom-0.1.8/src/hcom.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.1.6
+Version: 0.1.8
 Summary: Lightweight CLI tool for real-time communication between Claude Code subagents using hooks
 Author-email: aannoo <your@email.com>
 License: MIT
@@ -92,7 +92,7 @@ hcom open test-writer --claude-args "-p 'write tests for any new code'"
 hcom open reviewer --claude-args "-p 'review when @mentioned'"
 
 # Pass multiple Claude flags
-hcom open orchestrator --claude-args "--model claude-3-opus 
+hcom open orchestrator --claude-args "--model sonnet 
 --resume session_id"
 
 # Launch in specific directories
@@ -100,11 +100,12 @@ cd backend && hcom open api-specialist
 cd ../frontend && hcom open ui-specialist
 
 # Create named teams that can be @mentioned
-cd ~/api && hcom open --prefix api debugger
-cd ~/auth && hcom open --prefix auth debugger
+cd ~/api && hcom open --prefix api debugger  # Creates api-hovoa7
+cd ~/auth && hcom open --prefix auth debugger  # Creates auth-hovob8
 
-# Message specific teams
-hcom send "@api login works but API fails" # or in dashboard: hcom watch
+# Message specific teams or instances
+hcom send "@api login works but API fails"  # Messages all api-* instances
+hcom send "@hovoa7 can you check this?"     # Message specific instance by name
 ```
 
 
@@ -120,7 +121,7 @@ hcom send "@api login works but API fails" # or in dashboard: hcom watch
 ### Automation Commands
 | Command | Description |
 |---------|-------------|
-| `hcom send 'message'` | Send message |
+| `hcom send 'message'` | Send message to chat |
 | `hcom watch --logs` | View message history (non-interactive) |
 | `hcom watch --status` | Show instance status (non-interactive) |
 | `hcom watch --wait [timeout]` | Wait and notify for new messages |
@@ -195,7 +196,7 @@ HCOM_MAX_MESSAGE_SIZE=8192 hcom send "$(cat long_report.txt)"
 
 hcom adds hooks to your project directory's `.claude/settings.local.json`:
 
-1. **Sending**: Claude writes messages with `echo "HCOM_SEND:message"` - captured by PostToolUse hook
+1. **Sending**: Claude agents use `echo "HCOM_SEND:message"` internally (you use `hcom send` from terminal)
 2. **Receiving**: Other Claudes get notified via Stop hook
 3. **Waiting**: Stop hook keeps Claude in a waiting state for new messages