diff --git a/README.md b/README.md index 9edc4e7..a2aec10 100644 --- a/README.md +++ b/README.md @@ -5,21 +5,17 @@ [![Rust](https://img.shields.io/badge/Built_with-Rust-dea584)](https://www.rust-lang.org/) [![GitHub stars](https://img.shields.io/github/stars/aannoo/hcom)](https://github.com/aannoo/hcom/stargazers) -Agents running in separate terminals are isolated from each other. Context doesn't transfer, decisions get repeated, file edits collide. - -hcom connects your existing AI tools. When one agent edits a file, runs a command, or sends a message, other agents find out immediately. +**Multi-agent communication for your terminal.** hcom connects AI coding agents running in separate terminals so they can message, watch, and spawn each other. No more isolated contexts, repeated decisions, or colliding file edits. ![demo](https://raw.githubusercontent.com/aannoo/hcom/refs/heads/assets/screencapture-new-new.gif) ---- - -## Quickstart +## Install ```bash curl -fsSL https://raw.githubusercontent.com/aannoo/hcom/main/install.sh | sh ``` -
Or with pip/uv +
Or with pip / uv ```bash pip install hcom # or @@ -28,7 +24,9 @@ uv tool install hcom
-Run agents with `hcom` in front: +## Quickstart + +Launch agents with `hcom` in front: ```bash hcom claude @@ -37,50 +35,31 @@ hcom codex hcom opencode ``` -Prompt: +Tell any agent: > send a message to claude -Open the TUI: +Open the TUI dashboard: ```bash hcom ``` ---- - ## How it works -Messages arrive mid-turn or wake idle agents immediately. - -If 2 agents edit the same file within 30 seconds, both get collision notifications. +Hooks record activity and deliver messages between agents through a local SQLite database: -Refer to agents by name, tool, terminal, branch, cwd, or set a custom tag. - -```bash -# hooks record activity and deliver messages -agent → hooks → db → hooks → other agent +``` +agent --> hooks --> db --> hooks --> other agent ``` ---- - - -## What you can do - -Tell any agent: - -> when codex goes idle send it the next task - -> watch gemini's file edits, review each and send feedback if any bugs - -> fork yourself to investigate the bug and report back - -> find which agent worked on terminal_id code, resume them and ask why it sucks - +- Messages arrive mid-turn or wake idle agents immediately +- If 2 agents edit the same file within 30 seconds, both get collision notifications +- Agents are addressable by name, tool, terminal, branch, cwd, or custom tag -
What agents can do +## Capabilities -| | | +| Capability | Command | |---|---| | Message each other (intents, threads, broadcast, @mentions) | `hcom send` | | Read each other's transcripts (ranges and detail levels) | `hcom transcript` | @@ -91,35 +70,26 @@ Tell any agent: | Kill agents and close their terminal panes/sessions | `hcom kill` | | Build context bundles (files, transcript, events) for handoffs | `hcom bundle` | -
- - ---- - -## Multi-agent workflows - -Included workflow scripts. - -**`hcom run confess`** - An agent (or background clone) writes an honesty self-eval. A spawned calibrator reads the target's transcript independently. A judge compares both reports and sends back a verdict via hcom message. - -**`hcom run debate`** - A judge spawns and sets up a debate with existing agents. It coordinates rounds in a shared thread where all agents see each other's arguments, with shared context of workspace files and transcripts. - -**`hcom run fatcow`** — headless agent reads every file in a path, subscribes to file edit events to stay current, and answers other agents on demand. - -Create your own by prompting: - -> "read `hcom run docs` then make a script that does X" +### Example prompts +> when codex goes idle send it the next task ---- +> watch gemini's file edits, review each and send feedback if any bugs -## Tools +> fork yourself to investigate the bug and report back -**Claude Code, Gemini CLI, Codex, OpenCode** — messages are delivered automatically, events are tracked. +> find which agent worked on terminal_id code, resume them and ask why it sucks -**Any AI tool that can run shell commands** - send and receive messages manually. Tell agent "run `hcom start`" +## Supported tools -**Any process** - fire and forget: `hcom send --from botname` +| Tool | Message delivery | +|------|------------------| +| **Claude Code** (including subagents) | Automatic | +| **Gemini CLI** | Automatic | +| **Codex** | Automatic | +| **OpenCode** | Automatic | +| Any AI tool that can run shell commands | Manual -- tell agent `hcom start` | +| Any process | Fire and forget: `hcom send --from botname` |
Claude Code headless @@ -128,6 +98,7 @@ Detached background process that stays alive. Manage via TUI. ```bash hcom claude -p 'say hi in hcom' ``` +
Claude Code subagents @@ -138,651 +109,102 @@ Run `hcom claude`. Then inside, prompt:
---- +## Multi-agent workflows + +Built-in workflow scripts you can run out of the box: + +| Script | What it does | +|--------|-------------| +| `hcom run confess` | An agent writes an honesty self-eval. A spawned calibrator reads the target's transcript independently. A judge compares both reports and sends back a verdict. | +| `hcom run debate` | A judge spawns a debate with existing agents. It coordinates rounds in a shared thread where all agents see each other's arguments, with shared context of workspace files and transcripts. | +| `hcom run fatcow` | A headless agent reads every file in a path, subscribes to file edit events to stay current, and answers other agents on demand. | -## Terminal +Create your own by prompting: + +> "read `hcom run docs` then make a script that does X" -Spawning works with any terminal emulator. Run `hcom config terminal --info` to set up a custom one. +User scripts go in `~/.hcom/scripts/` (`.sh` or `.py`). -Closing/killing works with kitty, wezterm (auto open/close panes), and tmux (background). +## Terminal support + +Spawning works with any terminal emulator. Closing/killing has full support for **kitty**, **wezterm**, and **tmux**. ```bash -hcom config terminal kitty # set +hcom config terminal kitty # set your terminal ``` ---- +Run `hcom config terminal --info` for the full list of presets and custom command setup. -## Cross-device +## Cross-device sync Connect agents across machines via MQTT relay: ```bash -# get token +# Create a relay group hcom relay new -# on each device +# On each device hcom relay connect ``` ---- - -## What gets installed +## Installation details -Hooks go into `~/` (or `HCOM_DIR`) on launch or `hcom start`. If you aren't using hcom, the hooks do nothing. +Hooks install into `~/` (or `HCOM_DIR`) on first launch or via `hcom start`. ```bash hcom hooks remove # safely remove only hcom hooks +hcom status # diagnostics ``` ```bash -HCOM_DIR=$PWD/.hcom # for sandbox or project local -``` - -```bash -hcom status # diagnostics +HCOM_DIR=$PWD/.hcom # sandbox / project-local mode ``` ---- - ## Reference
-CLI +CLI commands ``` -hcom (hook-comms) v0.7.3 - multi-agent communication +hcom (hook-comms) v0.7.4 - multi-agent communication Usage: -hcom TUI dashboard -hcom Run command + hcom TUI dashboard + hcom Run command Launch: -hcom [N] claude|gemini|codex|opencode [flags] [tool-args] -hcom r Resume stopped agent -hcom f Fork agent session -hcom kill Kill + close terminal pane + hcom [N] claude|gemini|codex|opencode [flags] [tool-args] + hcom r Resume stopped agent + hcom f Fork agent session + hcom kill Kill + close terminal pane Commands: -send Send message to your buddies -listen Block until message or event arrives -list Show agents, status, unread counts -events Query event stream, manage subscriptions -bundle Structured context packages for handoffs -transcript Read another agent's conversation -start Connect to hcom (run inside any AI tool) -stop Disconnect from hcom -config Get/set global and per-agent settings -run Execute workflow scripts -relay Cross-device sync + relay daemon -archive Query past hcom sessions -reset Archive and clear database -hooks Add or remove hooks -status Installation and diagnostics -term View/inject into agent PTY screens - - -## send - -Usage: - -Usage: - send @name -- message text Direct message - send @name1 @name2 -- message Multiple targets - send -- message text Broadcast to all - send @name Message from stdin (pipe or heredoc) - send @name --file Message from file - send @name --base64 Message from base64 string - - Everything after -- is the message (no quotes needed). - All flags must come before --. - - -Target matching: - @luna base name (matches luna, api-luna) - @api-luna exact full name - @api- prefix: all with tag 'api' - @luna:BOXE remote agent on another device - Underscore blocks prefix: @luna does NOT match luna_reviewer_1 - - -Envelope: - --intent request | inform | ack - request: expect a response - inform: FYI, no response needed - ack: replying to a request (requires --reply-to) - --reply-to Link to event ID (42 or 42:BOXE) - --thread Group related messages - - -Sender: - --from External sender identity (alias: -b) - --name Your identity (agent name or UUID) - - -Inline bundle (attach structured context): - --title Create and attach bundle inline - --description Bundle description (required with --title) - --events Event IDs/ranges: 1,2,5-10 - --files Comma-separated file paths - --transcript Format: 3-14:normal,6:full,22-30:detailed - --extends Parent bundle (optional) - See 'hcom bundle --help' for bundle details - - -Examples: - hcom send @luna -- Hello there! - hcom send @luna @nova --intent request -- Can you help? - hcom send -- Broadcast message to everyone - echo 'Complex message' | hcom send @luna - hcom send @luna <<'EOF' - Multi-line message with special chars - EOF - -## list - -Usage: - hcom list All alive agents, read receipts - -v Verbose (directory, session, etc) - --json JSON array of all agents - --names Just names, one per line - --format TPL Template per agent: --format '{name} {status}' - Fields: name, base_name, status, status_context, status_detail, - status_age_seconds, description, unread_count, tool, tag, directory, - session_id, parent_name, agent_id, headless, created_at, - hooks_bound, process_bound, transcript_path, background_log_file, - launch_context - - hcom list [self|] Single agent details - [field] Print specific field (status, directory, session_id, ...) - --json Output as JSON - --sh Shell exports: eval "$(hcom list self --sh)" - - hcom list --stopped [name] Stopped agents (from events) - --all All stopped (default: last 20) - - -Status icons: - ▶ active processing, reads messages very soon - ◉ listening idle, reads messages in <1s - ■ blocked needs human approval - ○ inactive dead or stale - ◦ unknown neutral - - -Tool labels: - [CLAUDE] [GEMINI] [CODEX] [OPENCODE] hcom-launched (PTY + hooks) - [claude] [gemini] [codex] [opencode] vanilla (hooks only) - [AD-HOC] manual polling - -## events - -Usage: - Query the event stream (messages, status changes, file edits, lifecycle) - - -Query: - events Last 20 events as JSON - --last N Limit count (default: 20) - --all Include archived sessions - --wait [SEC] Block until match (default: 60s) - --sql EXPR Raw SQL WHERE (ANDed with flags) - - -Filters (same flag repeated = OR, different flags = AND): - --agent NAME Agent name - --type TYPE message | status | life - --status VAL listening | active | blocked - --context PATTERN tool:Bash | deliver:X (supports * wildcard) - --action VAL created | started | ready | stopped | batch_launched - --cmd PATTERN Shell command (contains, ^prefix, $suffix, =exact, *glob) - --file PATH File write (*.py for glob, file.py for contains) - --collision Two agents edit same file within 30s - --from NAME Sender - --mention NAME @mention target - --intent VAL request | inform | ack - --thread NAME Thread name - --after TIME After timestamp (ISO-8601) - --before TIME Before timestamp (ISO-8601) - - -Shortcuts: - --idle NAME --agent NAME --status listening - --blocked NAME --agent NAME --status blocked - - -Subscribe (next matching event delivered as messages from [hcom-events]): - events sub list List active subscriptions - events sub [filters] [--once] Subscribe using filter flags (listed above) - events sub "SQL WHERE" [--once] Subscribe using raw SQL - --once Auto-remove after first match - --for Subscribe on behalf of another agent - events unsub Remove subscription - - -Examples: - events --cmd git --agent peso - events sub --idle peso Notified when peso goes idle - events sub --file '*.py' --once One-shot: next .py file write - - -SQL reference (events_v view): - Base id, timestamp, type, instance - msg_* from, text, scope, sender_kind, delivered_to[], mentions[], intent, thread, reply_to - status_* val, context, detail - life_* action, by, batch_id, reason - - type message, status, life - msg_scope broadcast, mentions - msg_sender_kind instance, external, system - status_context tool:X, deliver:X, approval, prompt, exit:X - life_action created, ready, stopped, batch_launched - - delivered_to/mentions are JSON arrays — use LIKE '%name%' not = 'name' - Use <> instead of != for SQL negation - -## stop - -Usage: - hcom stop Disconnect self from hcom - hcom stop Disconnect specific agent - hcom stop ... Disconnect multiple - hcom stop tag: Disconnect all with tag - hcom stop all Disconnect all agents - - -## start - -Usage: - hcom start Connect to hcom (from inside any AI session) - hcom start --as Reclaim identity (after compaction/resume/clear) - hcom start --orphan Recover orphaned PTY process from pidtrack - - - Inside a sandbox? Prefix all hcom commands with: HCOM_DIR=$PWD/.hcom - -## listen - -Usage: - hcom listen [timeout] Block until message arrives - [timeout] Timeout in seconds (alias for --timeout) - --timeout N Timeout in seconds (default: 86400) - --json Output messages as JSON - - -Filter flags: - Supports all filter flags from 'events' command - (--agent, --type, --status, --file, --cmd, --from, --intent, etc.) - Run 'hcom events --help' for full list - Filters combine with --sql using AND logic - - -SQL filter mode: - --sql "type='message'" Custom SQL against events_v - --sql stopped:name Preset: wait for agent to stop - --idle NAME Shortcut: wait for agent to go idle - - -Exit codes: - 0 Message received / event matched - 1 Timeout or error - - Quick unread check: hcom listen 1 - -## status - -Usage: - hcom status Installation status and diagnostics - hcom status --logs Include recent errors and warnings - hcom status --json Machine-readable output - -## config - -Usage: - hcom config Show effective config (with sources) - hcom config Get one key - hcom config Set one key - hcom config --info Detailed help for a key - --json / --edit / --reset - - -Per-agent: - hcom config -i [key] [val] tag, timeout, hints, subagent_timeout - - -Keys: - tag Group/label (agents become tag-*) - terminal Where new agent windows open - hints Text appended to all messages agent receives - notes Notes appended to agent bootstrap - subagent_timeout Subagent keep-alive seconds after task - claude_args / gemini_args / codex_args / opencode_args - auto_approve Auto-approve safe hcom commands - auto_subscribe Event auto-subscribe presets - name_export Export agent name to custom env var - hcom config --info for details - - Precedence: defaults < config.toml < env vars - Files: ~/.hcom/config.toml, ~/.hcom/config.env - HCOM_DIR: isolate per project (see 'hcom reset --help') - -## hooks - -Usage: - hcom hooks Show hook status - hcom hooks status Same as above - hcom hooks add [tool] Add hooks (claude | gemini | codex | opencode | all) - hcom hooks remove [tool] Remove hooks (claude | gemini | codex | opencode | all) - - Hooks enable automatic message delivery and status tracking. - Without hooks, use ad-hoc mode (run hcom start inside any AI tool). - Restart the tool after adding hooks to activate. - Remove cleans both global (~/) and HCOM_DIR-local if set. - -## archive - -Usage: - hcom archive List archived sessions (numbered) - hcom archive Query events from archive (1 = most recent) - hcom archive agents Query agents from archive - hcom archive Query by stable name (prefix match) - --here Filter to archives from current directory - --sql "expr" SQL WHERE filter - --last N Limit events (default: 20) - --json JSON output - -## reset - -Usage: - hcom reset Archive conversation, clear database - hcom reset all Stop all + clear db + remove hooks + reset config - - -Sandbox / local mode: - If you can't write to ~/.hcom, set: - export HCOM_DIR="$PWD/.hcom" - Hooks install under $PWD (.claude/.gemini/.codex) or ~/.config/opencode/, state in $HCOM_DIR - - To remove local setup: - hcom hooks remove && rm -rf "$HCOM_DIR" - - Explicit location: - export HCOM_DIR=/your/path/.hcom - - -## transcript - -Usage: - hcom transcript View agent's conversation (last 10) - hcom transcript N Show exchange N - hcom transcript N-M Show exchanges N through M - hcom transcript timeline User prompts across all agents by time - --last N Limit to last N exchanges (default: 10) - --full Show complete assistant responses - --detailed Show tool I/O, file edits, errors - --json JSON output - - hcom transcript search "pattern" Search hcom-tracked transcripts (rg/grep) - --live Only currently alive agents - --all All transcripts (includes non-hcom sessions) - --limit N Max results (default: 20) - --agent TYPE Filter: claude | gemini | codex | opencode - --exclude-self Exclude the searching agent's own transcript - --json JSON output - - Tip: Reference ranges in messages instead of copying: - "read my transcript range 7-10 --full" - -## bundle - -Usage: - hcom bundle List recent bundles (alias: bundle list) - hcom bundle list List recent bundles - --last N Limit count (default: 20) - --json Output JSON - - hcom bundle cat Expand full bundle content - Shows: metadata, files (metadata only), transcript (respects detail level), events - - hcom bundle prepare Show recent context, suggest template - --for Prepare for specific agent (default: self) - --last-transcript N Transcript entries to suggest (default: 20) - --last-events N Events to scan per category (default: 30) - --json Output JSON - --compact Hide how-to section - Shows suggested transcript ranges, relevant events, files - Outputs ready-to-use bundle create command - TIP: Skip 'bundle create' — use bundle flags directly in 'hcom send' - - hcom bundle show Show bundle by id/prefix - --json Output JSON - - hcom bundle create "title" Create bundle (positional or --title) - --title Bundle title (alternative to positional) - --description Bundle description (required) - --events 1,2,5-10 Event IDs/ranges, comma-separated (required) - --files a.py,b.py Comma-separated file paths (required) - --transcript RANGES Transcript with detail levels (required) - Format: range:detail (3-14:normal,6:full,22-30:detailed) - normal = truncated | full = complete | detailed = tools+edits - --extends Parent bundle for chaining - --bundle JSON Create from JSON payload - --bundle-file FILE Create from JSON file - --json Output JSON - - -JSON format: - { - "title": "Bundle Title", - "description": "What happened, decisions, state, next steps", - "refs": { - "events": ["123", "124-130"], - "files": ["src/auth.py", "tests/test_auth.py"], - "transcript": ["10-15:normal", "20:full", "30-35:detailed"] - }, - "extends": "bundle:abc123" - } - - hcom bundle chain Show bundle lineage - --json Output JSON - -## kill - -Usage: - hcom kill Kill process (+ close terminal pane) - hcom kill tag: Kill all with tag - hcom kill all Kill all with tracked PIDs - - -## term - -Usage: - hcom term Screen dump (all PTY instances) - hcom term [name] Screen dump for specific agent - --json Raw JSON output - - hcom term inject [text] Inject text into agent PTY - --enter Append \r (submit). Works alone or with text. - - hcom term debug on Enable PTY debug logging (all instances) - hcom term debug off Disable PTY debug logging - hcom term debug logs List debug log files - - -JSON fields: lines[], size[rows,cols], cursor[row,col], - ready, prompt_empty, input_text - - Debug toggle; instances detect within ~10s. - Logs: ~/.hcom/.tmp/logs/pty_debug/ - -## relay - -Usage: - hcom relay Show status and token - hcom relay new Create new relay group - hcom relay connect Join relay group - hcom relay on / off Enable/disable sync - - -Setup: - 1. 'relay new' to get token - 2. 'relay connect ' on each device - - -Custom broker: - hcom relay new --broker mqtts://host:port --password - hcom relay connect --password - - -Daemon: - hcom relay daemon Show daemon status - hcom relay daemon start Start the relay daemon - hcom relay daemon stop Stop the daemon (SIGKILL after 5s) - hcom relay daemon restart Restart the daemon - - -## run - -Usage: - hcom run List available workflow/launch scripts and more info - hcom run [args] Execute script - hcom run --help Script options - hcom run docs CLI reference + config + script creation guide - - Docs sections: - hcom run docs --cli CLI reference only - hcom run docs --config Config settings only - hcom run docs --scripts Script creation guide - - User scripts: ~/.hcom/scripts/ - -## claude - -Usage: - hcom [N] claude [args...] Launch N Claude agents (default N=1) - - hcom claude Runs in current terminal - hcom 3 claude Opens 3 new terminal windows - hcom 3 claude -p "prompt" 3 headless in background - hcom 1 claude --agent .claude/agents/.md - -hcom Flags: - --tag Group tag (names become tag-*) - --terminal Where new windows open - --hcom-prompt Initial prompt - --hcom-system-prompt System prompt - -Environment: - HCOM_CLAUDE_ARGS Default args (merged with CLI) - HCOM_TAG Group tag (agents become tag-*) - HCOM_TERMINAL default | | "cmd {script}" - HCOM_HINTS Appended to messages received - HCOM_NOTES One-time bootstrap notes - HCOM_SUBAGENT_TIMEOUT Seconds subagents keep-alive after task - -Resume / Fork: - hcom r Resume stopped agent by name - hcom f Fork agent session (active or stopped) - - Run "claude --help" for claude options. - Run "hcom config terminal --info" for terminal presets. - -## gemini - -Usage: - hcom [N] gemini [args...] Launch N Gemini agents (default N=1) - - hcom gemini Runs in current terminal - hcom 3 gemini Opens 3 new terminal windows - hcom N gemini --yolo Flags forwarded to gemini - -hcom Flags: - --tag Group tag (names become tag-*) - --terminal Where new windows open - --hcom-prompt Initial prompt - --hcom-system-prompt System prompt - -Environment: - HCOM_GEMINI_ARGS Default args (merged with CLI) - HCOM_TAG Group tag (agents become tag-*) - HCOM_TERMINAL default | | "cmd {script}" - HCOM_HINTS Appended to messages received - HCOM_NOTES One-time bootstrap notes - HCOM_GEMINI_SYSTEM_PROMPT System prompt (env var) - -Resume: - hcom r Resume stopped agent by name - Gemini does not support session forking (hcom f). - - Run "gemini --help" for gemini options. - Run "hcom config terminal --info" for terminal presets. - -## codex - -Usage: - hcom [N] codex [args...] Launch N Codex agents (default N=1) - - hcom codex Runs in current terminal - hcom 3 codex Opens 3 new terminal windows - hcom codex --sandbox danger-full-access Flags forwarded to codex - -hcom Flags: - --tag Group tag (names become tag-*) - --terminal Where new windows open - --hcom-prompt Initial prompt - --hcom-system-prompt System prompt - -Environment: - HCOM_CODEX_ARGS Default args (merged with CLI) - HCOM_TAG Group tag (agents become tag-*) - HCOM_TERMINAL default | | "cmd {script}" - HCOM_HINTS Appended to messages received - HCOM_NOTES One-time bootstrap notes - HCOM_CODEX_SYSTEM_PROMPT System prompt (env var or config) - -Resume / Fork: - hcom r Resume stopped agent by name - hcom f Fork agent session (active or stopped) - - Run "codex --help" for codex options. - Run "hcom config terminal --info" for terminal presets. - -## opencode - -Usage: - hcom [N] opencode [args...] Launch N OpenCode agents (default N=1) - - hcom opencode Runs in current terminal - hcom 3 opencode Opens 3 new terminal windows - -hcom Flags: - --tag Group tag (names become tag-*) - --terminal Where new windows open - --hcom-prompt Initial prompt - --hcom-system-prompt System prompt - -Environment: - HCOM_OPENCODE_ARGS Default args (merged with CLI) - HCOM_TAG Group tag (agents become tag-*) - HCOM_TERMINAL default | | "cmd {script}" - HCOM_HINTS Appended to messages received - HCOM_NOTES One-time bootstrap notes - -Resume / Fork: - hcom r Resume stopped agent by name - hcom f Fork agent session (active or stopped) - - Run "opencode --help" for opencode options. - Run "hcom config terminal --info" for terminal presets. + send Send message to your buddies + listen Block until message or event arrives + list Show agents, status, unread counts + events Query event stream, manage subscriptions + bundle Structured context packages for handoffs + transcript Read another agent's conversation + start Connect to hcom (run inside any AI tool) + stop Disconnect from hcom + config Get/set global and per-agent settings + run Execute workflow scripts + relay Cross-device sync + relay daemon + archive Query past hcom sessions + reset Archive and clear database + hooks Add or remove hooks + status Installation and diagnostics + term View/inject into agent PTY screens ``` +Run `hcom --help` for detailed usage on any command. +
-Config +Configuration ``` -# Config Settings - File: ~/.hcom/config.toml Precedence: defaults < config.toml < env vars @@ -792,362 +214,47 @@ Commands: hcom config --info Detailed help for a setting hcom config --edit Open in $EDITOR -HCOM_TAG - Group tag for launched instances - -Purpose: - Creates named groups of agents that can be addressed together. - When set, launched instances get names like: - - -Usage: - hcom config tag myteam # Set tag - hcom config tag "" # Clear tag - - # Or via environment: - HCOM_TAG=myteam hcom 3 claude - -Effect: - Without tag: launches create → luna, nova, kira - With tag "dev": launches create → dev-luna, dev-nova, dev-kira - -Addressing: - @dev → sends to all agents with tag "dev" - @dev-luna → sends to specific agent - -Allowed characters: letters, numbers, hyphens (a-z, A-Z, 0-9, -) - -HCOM_HINTS - Text injected with all messages - -Purpose: - Appends text to every message received by launched agents. - Useful for persistent instructions or context. - -Usage: - hcom config hints "Always respond in JSON format" - hcom config hints "" # Clear hints - -Example: - hcom config hints "You are part of team-alpha. Coordinate with @team-alpha members." - -Notes: - - Hints are appended to message content, not system prompt - - Each agent can have different hints (set via hcom config -i hints) - - Global hints apply to all new launches - -HCOM_NOTES - One-time notes appended to bootstrap - - Custom text added to agent system context at startup. - Unlike HCOM_HINTS (per-message), this is injected once and does not repeat. - -Usage: - hcom config notes "Always check hcom list before spawning new agents" - hcom config notes "" # Clear - HCOM_NOTES="tips" hcom 1 claude # Per-launch override - - Changing after launch has no effect (bootstrap already delivered). - -HCOM_TIMEOUT - Advanced: idle timeout for headless/vanilla Claude (seconds) - -Default: 86400 (24 hours) - -This setting only applies to: - - Headless Claude: hcom N claude -p - - Vanilla Claude: claude + hcom start - -Does NOT apply to: - - Interactive PTY mode: hcom N claude (main path) - - Gemini or Codex - -How it works: - - Claude's Stop hook runs when Claude goes idle - - Hook waits up to TIMEOUT seconds for a message - - If no message within timeout, instance is unregistered - -Usage (if needed): - hcom config HCOM_TIMEOUT 3600 # 1 hour - export HCOM_TIMEOUT=3600 # via environment - -HCOM_SUBAGENT_TIMEOUT - Timeout for Claude subagents (seconds) - -Default: 30 - -Purpose: - How long Claude waits for a subagent (Task tool) to complete. - Shorter than main timeout since subagents should be quick. - -Usage: - hcom config subagent_timeout 60 # 1 minute - hcom config subagent_timeout 30 # 30 seconds (default) - -Notes: - - Only applies to Claude Code's Task tool spawned agents - - Parent agent blocks until subagent completes or times out - - Increase for complex subagent tasks - -HCOM_CLAUDE_ARGS - Default args passed to claude on launch - -Example: hcom config claude_args "--model opus" -Clear: hcom config claude_args "" - -Merged with launch-time cli args (launch args win on conflict). - -HCOM_GEMINI_ARGS - Default args passed to gemini on launch +Per-agent: hcom config -i [key] [val] -Example: hcom config gemini_args "--model gemini-2.5-flash" -Clear: hcom config gemini_args "" - -Merged with launch-time cli args (launch args win on conflict). - -HCOM_CODEX_ARGS - Default args passed to codex on launch - -Example: hcom config codex_args "--search" -Clear: hcom config codex_args "" - -Merged with launch-time cli args (launch args win on conflict). - -HCOM_OPENCODE_ARGS - Default args passed to opencode on launch - -Example: hcom config opencode_args "--model o3" -Clear: hcom config opencode_args "" - -Merged with launch-time cli args (launch args win on conflict). - -HCOM_CODEX_SANDBOX_MODE - Codex sandbox mode (e.g., off) (string) - -HCOM_GEMINI_SYSTEM_PROMPT - System prompt for gemini on launch (string) - -HCOM_CODEX_SYSTEM_PROMPT - System prompt for codex on launch (string) - -HCOM_TERMINAL — where hcom opens new agent windows - -Managed (open + close on kill): - kitty auto split/tab/window - wezterm auto tab/split/window - tmux detached sessions - cmux workspaces - - Variants: - kitty: kitty-window, kitty-tab, kitty-split - wezterm: wezterm-window, wezterm-tab, wezterm-split - tmux: tmux-split - -Other (opens window only): - Terminal.app - iTerm - Ghostty - alacritty - ttab - zellij - waveterm - -Custom command (open only): - hcom config terminal "my-terminal -e bash {script}" - -Custom preset with close (~/.hcom/config.toml): - [terminal.presets.myterm] - open = "myterm spawn -- bash {script}" - close = "myterm kill --id {pane_id}" - binary = "myterm" - pane_id_env = "MYTERM_PANE_ID" - -Placeholders: - {script} = hcom-generated launch wrapper script path - {pane_id} = pane/window/workspace ID from pane_id_env; falls back to {id} - {process_id} = HCOM_PROCESS_ID for the launched agent - {pid} = launched terminal process ID - {id} = first line of stdout captured from the open command - -Set: hcom config terminal kitty -Reset: hcom config terminal default - -HCOM_AUTO_APPROVE - Auto-approve safe hcom commands - -Purpose: - When enabled, Claude/Gemini/Codex auto-approve "safe" hcom commands - without requiring user confirmation. - -Usage: - hcom config auto_approve 1 # Enable auto-approve - hcom config auto_approve 0 # Disable (require approval) - -Safe commands (auto-approved when enabled): - send, start, list, events, listen, relay, config, - transcript, archive, status, help, --help, --version - -Always require approval: - - hcom reset (archives and clears database) - - hcom stop (stops instances) - - hcom claude (launches new instances) - -Values: 1, true, yes, on (enabled) | 0, false, no, off, "" (disabled) - -HCOM_AUTO_SUBSCRIBE - Auto-subscribe event presets for new instances - -Default: collision - -Purpose: - Comma-separated list of event subscriptions automatically added - when an instance registers with 'hcom start'. - -Usage: - hcom config auto_subscribe "collision,created" - hcom config auto_subscribe "" # No auto-subscribe - -Available presets: - collision - Alert when agents edit same file (within 30s window) - created - Notify when new instances join - stopped - Notify when instances leave - blocked - Notify when any instance is blocked (needs approval) - -Notes: - - Instances can add/remove subscriptions at runtime - - See 'hcom events --help' for subscription management - -HCOM_NAME_EXPORT - Export instance name to custom env var - -Purpose: - When set, launched instances will have their name exported to - the specified environment variable. Useful for scripts that need - to reference the current instance name. - -Usage: - hcom config name_export "MY_AGENT_NAME" # Export to MY_AGENT_NAME - hcom config name_export "" # Disable export - -Example: - # Set export variable - hcom config name_export "HCOM_NAME" - - # Now launched instances have: - # HCOM_NAME=luna (or whatever name was generated) - - # Scripts can use it: - # hcom send "@$HCOM_NAME completed task" - -Notes: - - Only affects hcom-launched instances (hcom N claude/gemini/codex) - - Variable name must be a valid shell identifier - - Works alongside HCOM_PROCESS_ID (always set) for identity - -HCOM_RELAY - MQTT broker URL - -Empty = use public brokers (broker.emqx.io, broker.hivemq.com, test.mosquitto.org). -Set automatically by 'hcom relay new' (pins first working broker). - -Private broker: hcom relay new --broker mqtts://host:port - -HCOM_RELAY_ID - Shared UUID for relay group - -Generated by 'hcom relay new'. Other devices join with 'hcom relay connect '. -All devices with the same relay_id sync state via MQTT pub/sub. - -HCOM_RELAY_TOKEN - Auth token for MQTT broker - -Optional. Set via 'hcom relay new --password ' or directly here. -Only needed if your broker requires authentication. - -HCOM_RELAY_ENABLED - Enable or disable relay sync - -Default: true (when relay is configured) - -Usage: - hcom config relay_enabled false Disable relay sync - hcom config relay_enabled true Re-enable relay sync - -Temporarily disables MQTT sync without removing relay configuration. - -Per-instance config: hcom config -i [value] - Keys: tag, timeout, hints, subagent_timeout +Keys: + tag Group/label (agents become tag-*) + terminal Where new agent windows open + hints Text appended to all messages agent receives + notes Notes appended to agent bootstrap + subagent_timeout Subagent keep-alive seconds after task + auto_approve Auto-approve safe hcom commands + auto_subscribe Event auto-subscribe presets (default: collision) + name_export Export agent name to custom env var + claude_args / gemini_args / codex_args / opencode_args ``` +See `hcom config --info` for detailed help on each setting. +
-Scripts +Custom scripts ``` -# Creating Custom Scripts - -## Location - - User scripts: ~/.hcom/scripts/ - File types: *.sh (bash), *.py (python3) +Location: ~/.hcom/scripts/ +File types: *.sh (bash), *.py (python3) User scripts shadow bundled scripts with the same name. -Scripts are discovered automatically — drop a file and run `hcom run `. -Add a description comment on line 2 (after shebang) — it shows in `hcom run` listings. - -## Shell Script Template - - #!/usr/bin/env bash - # Brief description shown in hcom run list. - set -euo pipefail - - name_flag="" - while [[ $# -gt 0 ]]; do - case "$1" in - -h|--help) echo "Usage: hcom run myscript [OPTIONS]"; exit 0 ;; - --name) name_flag="$2"; shift 2 ;; - --target) target="$2"; shift 2 ;; - *) shift ;; - esac - done - - name_arg="" - [[ -n "$name_flag" ]] && name_arg="--name $name_flag" - - # Your logic here - hcom send "@${target}" $name_arg --intent request -- "Do the task" - -## Identity Handling - -hcom passes --name to scripts automatically. Always parse and forward it: - - name_arg="" - [[ -n "$name_flag" ]] && name_arg="--name $name_flag" - hcom send @target $name_arg -- "message" - hcom list self --json $name_arg - -## Launching & Cleaning Up Agents - -Launch output includes "Names: " — parse to track spawned agents: - - LAUNCHED_NAMES=() - track_launch() { - local names=$(echo "$1" | grep '^Names: ' | sed 's/^Names: //') - for n in $names; do LAUNCHED_NAMES+=("$n"); done - } - cleanup() { - for name in "${LAUNCHED_NAMES[@]}"; do - hcom kill "$name" --go 2>/dev/null || true - done - } - trap cleanup ERR - - launch_out=$(hcom 1 claude --tag worker --go --headless 2>&1) - track_launch "$launch_out" - -## Reference Examples - -View source of any bundled or user script: +Drop a file and run: hcom run +View source of any script: hcom run --source -See `hcom run docs --cli` for full CLI command reference. -Available scripts: - hcom run confess --source - hcom run debate --source - hcom run fatcow --source +Full reference: + hcom run docs ```
-
-Build - +## Build from source ```bash # Prerequisites: Rust 1.86+ - git clone https://github.com/aannoo/hcom.git cd hcom ./build.sh @@ -1156,15 +263,10 @@ cd hcom ln -sf "$(pwd)/bin/hcom" ~/.local/bin/hcom ``` -
- - ---- - ## Contributing -Issues and PRs welcome. The codebase is Rust — `./build.sh` builds, runs tests, and copies the binary. +Issues and PRs welcome. The codebase is Rust -- `./build.sh` builds, runs tests, and copies the binary. ## License -MIT +[MIT](LICENSE)