hcom 0.6.1__tar.gz → 0.6.3__tar.gz

{hcom-0.6.1/src/hcom.egg-info → hcom-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.6.1
+Version: 0.6.3
 Summary: Launch multiple Claude Code instances (terminal, headless, or subagents) that communicate together in real time via hooks.
 Author: aannoo
 License-Expression: MIT
@@ -41,40 +41,38 @@ Launch multiple Claude Code instances (terminal, headless, or subagents) that co
 uvx hcom 2
 ```
 
-#### Install
+#### Run with installing
 ```bash
-pip install hcom   # or: uv tool install hcom
-```
+pip install hcom
 
-#### Use
-```bash
-hcom                     # UI - launch, monitor, message
-claude 'run hcom start'  # activate hcom for any claude code
+hcom                      # UI
+
+claude 'run hcom start'   # toggle hcom for any claude code
 ```
 
 
 ## What it does
 
-`hcom` adds hooks then launches terminals with Claude Code that remain active, waiting to respond to messages. Normal `claude` remains unaffected by hcom, but can opt-in/out with `hcom start`/`hcom stop`. Safely remove hcom hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
+Adds hooks that enable instant messaging between claude code instances. Launch multiple terminals/headless/subagents that remain active, waiting to respond. Normal `claude` remains unaffected by hcom, but can opt-in (`hcom start`) or opt-out (`hcom stop`) at runtime. Safely remove hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
 
 
 ## Commands
 
 | Command | Description
 |---------|-------------|
-| `hcom` | Interactive dashboard |
+| `hcom` | TUI dashboard |
 | `hcom <n>` | Launch `n` instances |
 | `hcom start` | Enable participation |
 | `hcom stop` | Disable participation |
 
 
-## Examples
+## Features
 
 #### communicate with task tool subagents
 ```bash
 claude 'use 3x task tool with task: say hi in hcom chat'
 # Each subagent gets unique identity and can communicate with siblings
-# Parent resumes after Task completes with full conversation history
+# Parent resumes with full conversation history
 ```
 
 #### persistent headless instances
@@ -104,6 +102,13 @@ claude              # Normal Claude Code
 'run hcom stop'     # Opt-out, continue as normal claude code
 ```
 
+#### async push notifications from anywhere
+```bash
+# Any process can message claude instances with custom identity
+hcom send --from background-worker 'i finished, now you go do stuff'
+```
+
+
 ---
 
 <details>
@@ -111,49 +116,56 @@ claude              # Normal Claude Code
 
 
 ```bash
-Usage: hcom   # UI
+Usage: hcom                           # TUI dashboard
        [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
-       hcom watch [--logs|--status|--wait [SEC]]
+       hcom watch [--type TYPE] [--instance NAME] [--last N] [--wait SEC]
+       hcom list [--json] [--verbose]
        hcom send "message"
        hcom stop [alias|all]
        hcom start [alias]
        hcom reset [logs|hooks|config]
 
 Launch Examples:
-  hcom 3             Open 3 terminals with claude connected to hcom
-  hcom 3 claude -p                            + Headless
+  hcom 3             open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                                       + headless
   HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
-  claude 'run hcom start'    claude code with prompt will also work
+  claude 'run hcom start'        claude code with prompt also works
 
 Commands:
-  watch              messaging/status/launch UI (same as hcom no args)
-    --logs           Print all messages
-    --status         Print instance status JSON
-    --wait [SEC]     Wait and notify for new message
+  watch               Query recent events (JSON per line)
+    --type TYPE       Filter by event type (message, status)
+    --instance ALIAS  Filter by instance
+    --last N          Limit to last N events (default: 20)
+    --wait SEC        Block until a matching event arrives
+
+  list                Show instance status/metadata
+    --json            Emit JSON (one instance per line)
+    --verbose         Include additional metadata
 
-  send "msg"         Send message to all instances
-  send "@alias msg"  Send to specific instance/group
+  send "msg"          Send message to all instances
+  send "@alias msg"   Send to specific instance/group
+    --from <name>     Custom external identity
 
-  stop               Stop current instance (from inside Claude)
-  stop <alias>       Stop specific instance
-  stop all           Stop all instances
+  stop                Stop current instance (from inside Claude)
+  stop <alias>        Stop specific instance
+  stop all            Stop all instances
 
-  start              Start current instance (from inside Claude)
-  start <alias>      Start specific instance
+  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
+  reset               Stop all + archive logs + remove hooks + clear config
+  reset logs          Clear + archive conversation
+  reset hooks         Safely remove hcom hooks from claude settings.json
+  reset config        Clear + archive 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_HINTS=text            Text appended to all messages received by instance
-  HCOM_TIMEOUT=secs          Time until disconnected from hcom chat (default 1800s / 30mins)
-  HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
-  HCOM_CLAUDE_ARGS=args      Claude CLI defaults (e.g., '-p --model opus "hello!"')
+  HCOM_TAG=name               Group tag (creates name-* instances)
+  HCOM_AGENT=type             Agent from .claude/agents/ (comma-separated for multiple)
+  HCOM_TERMINAL=mode          Terminal: new|here|print|"custom {script}"
+  HCOM_HINTS=text             Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs           Time until disconnected from hcom chat (default: 1800s / 30m)
+  HCOM_SUBAGENT_TIMEOUT=secs  Subagent idle timeout (default: 30s)
+  HCOM_CLAUDE_ARGS=args       Claude CLI defaults (e.g., '-p --model opus "hello!"')
 
   ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
 

{hcom-0.6.1 → hcom-0.6.3}/README.md

@@ -14,40 +14,38 @@ Launch multiple Claude Code instances (terminal, headless, or subagents) that co
 uvx hcom 2
 ```
 
-#### Install
+#### Run with installing
 ```bash
-pip install hcom   # or: uv tool install hcom
-```
+pip install hcom
 
-#### Use
-```bash
-hcom                     # UI - launch, monitor, message
-claude 'run hcom start'  # activate hcom for any claude code
+hcom                      # UI
+
+claude 'run hcom start'   # toggle hcom for any claude code
 ```
 
 
 ## What it does
 
-`hcom` adds hooks then launches terminals with Claude Code that remain active, waiting to respond to messages. Normal `claude` remains unaffected by hcom, but can opt-in/out with `hcom start`/`hcom stop`. Safely remove hcom hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
+Adds hooks that enable instant messaging between claude code instances. Launch multiple terminals/headless/subagents that remain active, waiting to respond. Normal `claude` remains unaffected by hcom, but can opt-in (`hcom start`) or opt-out (`hcom stop`) at runtime. Safely remove hooks with `hcom reset`. Works on Mac, Linux, Windows, Android.
 
 
 ## Commands
 
 | Command | Description
 |---------|-------------|
-| `hcom` | Interactive dashboard |
+| `hcom` | TUI dashboard |
 | `hcom <n>` | Launch `n` instances |
 | `hcom start` | Enable participation |
 | `hcom stop` | Disable participation |
 
 
-## Examples
+## Features
 
 #### communicate with task tool subagents
 ```bash
 claude 'use 3x task tool with task: say hi in hcom chat'
 # Each subagent gets unique identity and can communicate with siblings
-# Parent resumes after Task completes with full conversation history
+# Parent resumes with full conversation history
 ```
 
 #### persistent headless instances
@@ -77,6 +75,13 @@ claude              # Normal Claude Code
 'run hcom stop'     # Opt-out, continue as normal claude code
 ```
 
+#### async push notifications from anywhere
+```bash
+# Any process can message claude instances with custom identity
+hcom send --from background-worker 'i finished, now you go do stuff'
+```
+
+
 ---
 
 <details>
@@ -84,49 +89,56 @@ claude              # Normal Claude Code
 
 
 ```bash
-Usage: hcom   # UI
+Usage: hcom                           # TUI dashboard
        [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
-       hcom watch [--logs|--status|--wait [SEC]]
+       hcom watch [--type TYPE] [--instance NAME] [--last N] [--wait SEC]
+       hcom list [--json] [--verbose]
        hcom send "message"
        hcom stop [alias|all]
        hcom start [alias]
        hcom reset [logs|hooks|config]
 
 Launch Examples:
-  hcom 3             Open 3 terminals with claude connected to hcom
-  hcom 3 claude -p                            + Headless
+  hcom 3             open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                                       + headless
   HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
-  claude 'run hcom start'    claude code with prompt will also work
+  claude 'run hcom start'        claude code with prompt also works
 
 Commands:
-  watch              messaging/status/launch UI (same as hcom no args)
-    --logs           Print all messages
-    --status         Print instance status JSON
-    --wait [SEC]     Wait and notify for new message
+  watch               Query recent events (JSON per line)
+    --type TYPE       Filter by event type (message, status)
+    --instance ALIAS  Filter by instance
+    --last N          Limit to last N events (default: 20)
+    --wait SEC        Block until a matching event arrives
+
+  list                Show instance status/metadata
+    --json            Emit JSON (one instance per line)
+    --verbose         Include additional metadata
 
-  send "msg"         Send message to all instances
-  send "@alias msg"  Send to specific instance/group
+  send "msg"          Send message to all instances
+  send "@alias msg"   Send to specific instance/group
+    --from <name>     Custom external identity
 
-  stop               Stop current instance (from inside Claude)
-  stop <alias>       Stop specific instance
-  stop all           Stop all instances
+  stop                Stop current instance (from inside Claude)
+  stop <alias>        Stop specific instance
+  stop all            Stop all instances
 
-  start              Start current instance (from inside Claude)
-  start <alias>      Start specific instance
+  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
+  reset               Stop all + archive logs + remove hooks + clear config
+  reset logs          Clear + archive conversation
+  reset hooks         Safely remove hcom hooks from claude settings.json
+  reset config        Clear + archive 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_HINTS=text            Text appended to all messages received by instance
-  HCOM_TIMEOUT=secs          Time until disconnected from hcom chat (default 1800s / 30mins)
-  HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
-  HCOM_CLAUDE_ARGS=args      Claude CLI defaults (e.g., '-p --model opus "hello!"')
+  HCOM_TAG=name               Group tag (creates name-* instances)
+  HCOM_AGENT=type             Agent from .claude/agents/ (comma-separated for multiple)
+  HCOM_TERMINAL=mode          Terminal: new|here|print|"custom {script}"
+  HCOM_HINTS=text             Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs           Time until disconnected from hcom chat (default: 1800s / 30m)
+  HCOM_SUBAGENT_TIMEOUT=secs  Subagent idle timeout (default: 30s)
+  HCOM_CLAUDE_ARGS=args       Claude CLI defaults (e.g., '-p --model opus "hello!"')
 
   ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
 

{hcom-0.6.1 → hcom-0.6.3}/pyproject.toml

@@ -37,7 +37,7 @@ Issues = "https://github.com/aannoo/claude-hook-comms/issues"
 Documentation = "https://github.com/aannoo/claude-hook-comms#readme"
 
 [tool.setuptools]
-packages = ["hcom"]
+packages = ["hcom", "hcom.core", "hcom.hooks", "hcom.commands", "hcom.ui"]
 
 [tool.setuptools.package-dir]
 "" = "src"

hcom-0.6.3/src/hcom/__init__.py

@@ -0,0 +1,6 @@
+from .shared import __version__
+from .api import *
+from .api import __all__ as _api_all
+
+# Public API: version + all api.py exports (see api.py for details)
+__all__ = ['__version__'] + _api_all

hcom-0.6.3/src/hcom/api.py

@@ -0,0 +1,94 @@
+"""Public API for TUI and external tools
+
+Simple re-export module providing consistent import point.
+Not a service layer - just consolidates public surface.
+
+CLI and internal code can import from specific modules.
+TUI and plugins should import from api.py for stability.
+"""
+from __future__ import annotations
+
+# Core utilities
+from .core.config import (
+    get_config,
+    reload_config,
+    HcomConfig,
+    HcomConfigError,
+    ConfigSnapshot,
+    load_config_snapshot,
+    save_config_snapshot,
+    save_config,
+    dict_to_hcom_config,
+)
+from .core.paths import hcom_path, ensure_hcom_directories
+from .core.instances import (
+    get_instance_status,
+    set_status,
+    load_instance_position,
+    update_instance_position,
+)
+from .core.messages import (
+    send_message,
+    get_unread_messages,
+    get_read_receipts,
+)
+
+# Commands (for TUI to call directly)
+from .commands.admin import (
+    cmd_reset,
+    cmd_watch,
+    should_show_in_watch,
+)
+from .commands.lifecycle import (
+    cmd_launch,
+    cmd_start,
+    cmd_stop,
+)
+from .commands.messaging import cmd_send
+
+# Terminal utilities
+from .terminal import list_available_agents
+
+# Shared utilities and constants
+from .shared import (
+    ClaudeArgsSpec,
+    resolve_claude_args,
+)
+
+__all__ = [
+    # Config
+    'get_config',
+    'reload_config',
+    'HcomConfig',
+    'HcomConfigError',
+    'ConfigSnapshot',
+    'load_config_snapshot',
+    'save_config_snapshot',
+    'save_config',
+    'dict_to_hcom_config',
+    # Paths
+    'hcom_path',
+    'ensure_hcom_directories',
+    # Instances
+    'get_instance_status',
+    'set_status',
+    'load_instance_position',
+    'update_instance_position',
+    # Messages
+    'send_message',
+    'get_unread_messages',
+    'get_read_receipts',
+    # Commands
+    'cmd_launch',
+    'cmd_start',
+    'cmd_stop',
+    'cmd_send',
+    'cmd_reset',
+    'cmd_watch',
+    'should_show_in_watch',
+    # Terminal
+    'list_available_agents',
+    # Shared
+    'ClaudeArgsSpec',
+    'resolve_claude_args',
+]