hcom 0.3.1__tar.gz → 0.4.2.post3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hcom
-Version: 0.3.1
+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,52 +38,56 @@ 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** (optional)
+**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 clear` | Clear and start new conversation |
-| `hcom cleanup` | Safely remove hcom hooks, preserving your project settings |
+| `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.
+`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`.
+
 
-### Subagents in their own terminal
+### Interactive subagents in their own terminal
 ```bash
 # Launch subagents from your .claude/agents
-hcom open planner code-writer reviewer
+HCOM_AGENT=planner,code-writer,reviewer hcom 1
 ```
 
 ### Persistent headless instances
 ```bash
-# Launch one headless instance (default 30min timeout)
-hcom open -p
+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 --prefix cool  # Creates cool-hovoa7
-hcom open --prefix cool  # Creates 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'
 ```
 
-### Persistent thinking mode
+### Toggle HCOM in Claude Code
 ```bash
-# Thinking mode maintains for entire session
-HCOM_INITIAL_PROMPT="ultrathink and do x" hcom open
-# Every new message reply uses ultrathink
+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
 ```
 
 ---
@@ -107,26 +111,48 @@ HCOM_INITIAL_PROMPT="ultrathink and do x" hcom open
 <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 |
+```bash
+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:
+  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>
 
@@ -136,35 +162,29 @@ HCOM_INITIAL_PROMPT="ultrathink and do x" hcom open
 <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 3 headless instances that time out after 60 seconds of inactivity
+HCOM_TIMEOUT=60 hcom 3 claude -p
+# Stop all instances
+hcom stop all
 
 # Launch multiple of the same subagent
-hcom open reviewer reviewer reviewer
+HCOM_AGENT=reviewer hcom 3
 
-# Launch agent with specific prompt
-HCOM_INITIAL_PROMPT='write tests' hcom open test-writer
+# Launch mixed agents with team tag
+HCOM_TAG=api HCOM_AGENT=backend,frontend hcom 1
 
-# Resume instance (hcom chat will continue)
-hcom open --claude-args "--resume session_id"
+# Launch instance with specific prompt
+HCOM_PROMPT='write tests' HCOM_AGENT=test-writer hcom 1
 
-# Text appended to all messages recieved by instance
-HCOM_INSTANCE_HINTS="remember where you came from" hcom open
+# Pass claude args
+hcom 1 claude --resume session_id  # Resume instance (hcom chat continues)
 
-# Pass multiple Claude flags
-hcom open orchestrator --claude-args "--model sonnet --resume session_id"
+# Text appended to all messages received by instance
+HCOM_HINTS="remember where you came from" hcom 1
+
+# 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>
@@ -174,59 +194,40 @@ hcom open orchestrator --claude-args "--model sonnet --resume session_id"
 
 ### Configuration
 
-Settings can be changed two ways:
-
-#### Method 1: Environment variable (temporary, per-command/instance)
+Config file: `~/.hcom/config.env`
 
+All HCOM_* settings work from config file (persistent) or environment variable (temporary). Environment variables override config file.
 
-```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)
+| 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` |
 
-### 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 |
+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!"
-
-# Make instances timeout after 60 seconds instead of 30 minutes
-HCOM_WAIT_TIMEOUT=60 hcom open 3
+# Temporary override for one command
+HCOM_TIMEOUT=60 hcom 3
 
-# Custom welcome message
-HCOM_FIRST_USE_TEXT="Debug session for issue #123" hcom open 2
+# Set persistent config
+echo "HCOM_TIMEOUT=60" >> ~/.hcom/config.env
+echo "HCOM_TERMINAL=here" >> ~/.hcom/config.env
 
-# 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
@@ -237,8 +238,8 @@ When running `hcom watch`, each instance shows its current state:
 - ▷ **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
+- ○ **inactive** (red) - Closed/timed out/ended
+- ○ **unknown** (gray) - No status data or stale
 - **(bg)** suffix - Instance running in background headless mode
 
 </details>
@@ -248,34 +249,33 @@ 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 agents use `eval $HCOM send "message"` internally (you use `hcom send` from terminal or dashboard)
+1. **Sending**: Claude uses `hcom send "message"` to communicate
 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
+- **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 the chat
+- **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>
@@ -286,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
@@ -306,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
 
@@ -321,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)
@@ -394,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`
 
 ---
 
@@ -407,26 +408,28 @@ HCOM_TERMINAL_COMMAND="tmux split-window -h {script}" hcom open 3
 
 ### Archive Conversation / Start New
 ```bash
-hcom clear
+hcom stop all
 ```
 
-### Kill Running Instances
+### Stop Running Instances
 ```bash
-# Kill specific instance
-hcom kill hovoa7
+# Stop specific instance
+hcom stop hovoa7
 
-# Kill all instances
-hcom kill --all
+# Stop all and archive
+hcom stop all
 ```
 
-### Remove HCOM hooks from current directory
+### Start Stopped Instances
 ```bash
-hcom cleanup
+# Start specific instance
+hcom start hovoa7
 ```
 
-### Remove HCOM hooks from all directories
+### Remove HCOM hooks
 ```bash
-hcom cleanup --all
+# Stop all, archive conversation, remove hooks, clear config
+hcom reset
 ```
 
 ### Remove hcom Completely