hcom 0.4.0__tar.gz → 0.4.2.post3__tar.gz

{hcom-0.4.0/src/hcom.egg-info → hcom-0.4.2.post3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.4.0
+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
@@ -38,44 +38,47 @@ CLI tool for launching multiple Claude Code terminals with interactive [subagent
 
 **Run without installing** ([uv](https://docs.astral.sh/uv/#installation))
 ```bash
-uvx hcom open 2
+uvx hcom 2
 ```
 
 **Install**
 ```bash
-pip install hcom
-hcom open 2
+pip install hcom  # or: uv tool install hcom
+# then:
+hcom 2  # or tell claude to run hcom start
 ```
 
 | Commands |  |
 |---------|-------------|
-| `hcom open [n]` | Launch `n` instances or named agents |
+| `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 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, but can opt-in via `hcom start` and opt-out with `hcom stop`.
+`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 open -a planner -a code-writer -a reviewer
+HCOM_AGENT=planner,code-writer,reviewer hcom 1
 ```
 
 ### Persistent headless instances
 ```bash
-# Launch one headless instance (default 30min timeout)
-hcom open -p
-hcom stop # Stop it earlier than timeout
+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 open 2 -t cool  # Creates cool-hovoa7 & cool-homab8
+HCOM_TAG=cool hcom 2   # Creates cool-hovoa7 & cool-homab8
 hcom send '@cool hi, you are cool'
 hcom send '@homab8 hi, you are cooler'
 ```
@@ -83,8 +86,8 @@ 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
+'run hcom start'   # Start HCOM for this instance to receive messages
+'run hcom stop'   # Stop HCOM for this instance, continue as normal claude code
 ```
 
 ---
@@ -109,46 +112,46 @@ claude  # Start normal Claude Code
 <summary><strong>🥨 All Commands</strong></summary>
 
 ```bash
-Usage:
-  hcom open [count] [-a agent]... [-t prefix] [-p] [-- claude-args]
-  hcom watch [--logs|--status|--wait [SEC]]
-  hcom stop [target] [--force]
-  hcom start [target]
-  hcom send "msg"
+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:
-  open                 Launch Claude instances (default count: 1)
-  watch                Monitor conversation dashboard
-  stop                 Stop instances, clear conversation, or remove hooks
-  start                Start stopped instances
-  send                 Send message to instances
-
-Open options:
-  [count]              Number of instances per agent (default 1)
-  -a, --agent AGENT    Agent to launch (repeatable)
-  -t, --prefix PREFIX  Team prefix for names
-  -p, --background     Launch in background
-
-Stop targets:
-  (no arg)             Stop HCOM for current instance (when inside)
-  <alias>              Stop HCOM for specific instance
-  all                  Stop all instances + clear & archive conversation
-  hooking              Remove hooks from current directory
-  hooking --all        Remove hooks from all tracked directories
-  everything           Stop all + clear conversation + remove all hooks
-
-Start targets:
-  (no arg)             Start HCOM for current instance (when inside)
-  <alias>              Start HCOM for specific instance
-  hooking              Install hooks in current directory
-
-Watch options:
-  --logs               Show message history
-  --status             Show instance status JSON
-  --wait [SEC]         Wait for new messages (default 60s)
-
-Stop flags:
-  --force              Force stop (deny Bash tool use)
+  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>
@@ -160,27 +163,29 @@ Stop flags:
 
 ```bash
 # Launch 3 headless instances that time out after 60 seconds of inactivity
-HCOM_WAIT_TIMEOUT="60" hcom open 3 -p
+HCOM_TIMEOUT=60 hcom 3 claude -p
 # Stop all instances
 hcom stop all
 
 # Launch multiple of the same subagent
-hcom open 3 -a reviewer
+HCOM_AGENT=reviewer hcom 3
 
-# Launch mixed agents with team prefix
-hcom open -t api -a backend -a frontend
+# Launch mixed agents with team tag
+HCOM_TAG=api HCOM_AGENT=backend,frontend hcom 1
 
-# Launch agent with specific prompt
-HCOM_INITIAL_PROMPT='write tests' hcom open -a test-writer
+# Launch instance with specific prompt
+HCOM_PROMPT='write tests' HCOM_AGENT=test-writer hcom 1
 
-# Resume instance (hcom chat will continue)
-hcom open -- --resume session_id
+# Pass claude args
+hcom 1 claude --resume session_id  # Resume instance (hcom chat continues)
 
-# Text appended to all messages recieved by instance
-HCOM_INSTANCE_HINTS="remember where you came from" hcom open
+# Text appended to all messages received by instance
+HCOM_HINTS="remember where you came from" hcom 1
 
-# Pass multiple Claude flags
-hcom open -a orchestrator -- --model sonnet --resume session_id
+# 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>
 
@@ -189,59 +194,40 @@ hcom open -a orchestrator -- --model sonnet --resume session_id
 
 ### 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: `~/.hcom/config.env`
 
-### Config File Location
+All HCOM_* settings work from config file (persistent) or environment variable (temporary). Environment variables override config file.
 
-`~/.hcom/config.json`
+| 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` |
 
-| 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 |
+Any other environment variables in config.env are passed to Claude Code instances (e.g., ANTHROPIC_MODEL).
 
 ### Examples
 
 ```bash
-# Change your name for one command
-HCOM_SENDER_NAME="coolguy" hcom send "LGTM!"
+# Temporary override for one command
+HCOM_TIMEOUT=60 hcom 3
 
-# Make instances timeout after 60 seconds instead of 30 minutes
-HCOM_WAIT_TIMEOUT=60 hcom open 3
+# Set persistent config
+echo "HCOM_TIMEOUT=60" >> ~/.hcom/config.env
+echo "HCOM_TERMINAL=here" >> ~/.hcom/config.env
 
-# 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
+# Pass Claude Code env vars
+ANTHROPIC_MODEL=opus hcom 3
 ```
 
 **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
+# Temporary environment variable
+$env:HCOM_TERMINAL="here"; hcom 1
+$env:HCOM_TIMEOUT="60"; hcom 3
 ```
 
 ### Status Indicators
@@ -263,7 +249,7 @@ When running `hcom watch`, each instance shows its current state:
 
 ### Hooks!
 
-hcom adds hooks to your project directory's `.claude/settings.local.json`:
+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
@@ -272,25 +258,24 @@ hcom adds hooks to your project directory's `.claude/settings.local.json`:
 - **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
+- **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 open` join automatically, normal instances can use `hcom start`/`stop`
+- **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/
 ├── hcom.log       # Conversation log
 ├── instances/     # Instance tracking
 ├── logs/          # Background process logs
-├── config.json    # Configuration
+├── config.env     # Configuration
 └── archive/       # Archived sessions
 
-your-project/  
-└── .claude/
-    └── settings.local.json  # hcom hooks
+~/.claude/
+└── settings.json  # hcom hooks (global)
 ```
 
 </details>
@@ -301,14 +286,15 @@ your-project/
 
 ### 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
+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_MODE=same_terminal hcom open
+HCOM_TERMINAL=here hcom 1
 ```
 
 ### Default Terminals
@@ -321,7 +307,7 @@ HCOM_TERMINAL_MODE=same_terminal hcom open
 
 ### Custom Terminals
 
-Configure `terminal_command` in `~/.hcom/config.json` (permanent) or environment variables (temporary).
+Configure in `~/.hcom/config.env` (permanent) or environment variables (temporary).
 
 #### How to use this
 
@@ -336,61 +322,61 @@ Example template: `your_terminal_command --execute "bash {script}"`
 ### Custom Terminal Examples
 
 #### iTerm2
-```json
-"terminal_command": "open -a iTerm {script}"
+```bash
+HCOM_TERMINAL="open -a iTerm {script}"
 ```
 
 #### [ttab](https://github.com/mklement0/ttab) (new tab instead of new window in Terminal.app)
-```json
-"terminal_command": "ttab {script}"
+```bash
+HCOM_TERMINAL="ttab {script}"
 ```
 
 #### [wttab](https://github.com/lalilaloe/wttab) (new tab in Windows Terminal)
-```json
-"terminal_command": "wttab {script}"
+```bash
+HCOM_TERMINAL="wttab {script}"
 ```
 
 #### More
-```json
+```bash
 # WezTerm Linux/Windows
-"terminal_command": "wezterm start -- bash {script}"
+HCOM_TERMINAL="wezterm start -- bash {script}"
 
 # Tabs from within WezTerm
-"terminal_command": "wezterm cli spawn -- bash {script}"
+HCOM_TERMINAL="wezterm cli spawn -- bash {script}"
 
 # WezTerm macOS:
-"terminal_command": "open -n -a WezTerm.app --args start -- bash {script}"
+HCOM_TERMINAL="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}"
+HCOM_TERMINAL="/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}"
+HCOM_TERMINAL="wsh run -- bash {script}"
 
 # Alacritty macOS:
-"terminal_command": "open -n -a Alacritty.app --args -e bash {script}"
+HCOM_TERMINAL="open -n -a Alacritty.app --args -e bash {script}"
 
 # Alacritty Linux:
-"terminal_command": "alacritty -e bash {script}"
+HCOM_TERMINAL="alacritty -e bash {script}"
 
 # Kitty macOS:
-"terminal_command": "open -n -a kitty.app --args {script}"
+HCOM_TERMINAL="open -n -a kitty.app --args {script}"
 
 # Kitty Linux
-"terminal_command": "kitty {script}"
+HCOM_TERMINAL="kitty {script}"
 ```
 
 #### tmux
-```json
-"terminal_command": "tmux new-window -n hcom {script}"
+```bash
+HCOM_TERMINAL="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
+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_COMMAND="tmux split-window -h {script}" hcom open 3
+HCOM_TERMINAL="tmux split-window -h {script}" hcom 3
 ```
 
 ### Android (Termux)
@@ -409,7 +395,7 @@ HCOM_TERMINAL_COMMAND="tmux split-window -h {script}" hcom open 3
    ```
 4. Enable: "Display over other apps" permission for visible terminals
 
-5. Run: `hcom open`
+5. Run: `hcom 1`
 
 ---
 
@@ -442,11 +428,8 @@ hcom start hovoa7
 
 ### Remove HCOM hooks
 ```bash
-# Current directory
-hcom stop hooking
-
-# All directories
-hcom stop hooking --all
+# Stop all, archive conversation, remove hooks, clear config
+hcom reset
 ```
 
 ### Remove hcom Completely