Skip to main content

​
Overview

Launch one or more AI agents (Claude, Gemini, Codex, OpenCode) with automatic hcom integration, message delivery, and event tracking.

​
Syntax

hcom [N] <tool> [FLAGS] [TOOL_ARGS]
​
N
number
Number of agents to launch (default: 1)
  • Maximum for Claude: 100
  • Maximum for others: 10
​
tool
string
required
AI tool to launch: claude, gemini, codex, or opencode

​
hcom Flags

These flags configure hcom behavior and are processed before being passed to the tool.
​
--tag
string
Group tag - launched agents get names like tag-*
hcom 3 claude --tag dev
# Creates: dev-luna, dev-nova, dev-kira
​
--terminal
string
Terminal preset for new windowsOptions: kitty, wezterm, tmux, iTerm, Terminal.app, ghostty, alacritty, or custom
hcom 2 claude --terminal kitty-tab
​
--headless
boolean
Launch in background without terminal window (Claude only)Equivalent to claude -p mode
​
--hcom-prompt
string
Initial prompt to send after launch
hcom claude --hcom-prompt "Say hi in hcom"
​
--hcom-system-prompt
string
Custom system prompt appended to agent bootstrapAlias: --system
​
--batch-id
string
Custom batch ID for grouping launches (auto-generated if not provided)
​
--run-here
boolean
Run in current terminal instead of spawning new window (when N=1)

​
Global Flags

​
--go
boolean
Skip confirmation preview when launching from inside an AI toolRequired when launching with args or large batches from Claude/Gemini/Codex/OpenCode
​
--name
string
Launcher identity (for tracking who initiated the launch)

​
Tool-Specific Arguments

Any arguments not recognized as hcom flags are passed directly to the tool CLI. 
# Claude with model override
hcom claude --model opus

# Gemini with specific model
hcom gemini -m gemini-2.5-flash

# Codex with sandbox mode
hcom codex --sandbox off

# OpenCode (all args passed through)
hcom opencode --verbose

​
Environment Variables

​
HCOM_TAG
string
Default group tag (overridden by --tag flag)
​
HCOM_TERMINAL
string
Default terminal preset (overridden by --terminal flag)Default: default (auto-detect current terminal)
​
HCOM_HINTS
string
Text appended to all messages received by launched agents
​
HCOM_NOTES
string
One-time bootstrap notes shown at startup
​
HCOM_SUBAGENT_TIMEOUT
number
Seconds subagents stay alive after task completionDefault: 30
​
HCOM_CLAUDE_ARGS
string
Default args merged with CLI args for Claude launchesExample: --model opus --verbose
​
HCOM_GEMINI_ARGS
string
Default args for Gemini launches
​
HCOM_CODEX_ARGS
string
Default args for Codex launches
​
HCOM_OPENCODE_ARGS
string
Default args for OpenCode launches

​
Examples

​
Basic Launch

# Single Claude agent in current terminal
hcom claude

# 3 Gemini agents in new windows
hcom 3 gemini

# Single OpenCode agent
hcom opencode

​
Launch with Tag

# Create a team of agents
hcom 3 claude --tag team-alpha
# Creates: team-alpha-luna, team-alpha-nova, team-alpha-kira

# Message the team
hcom send @team-alpha -- All agents coordinate on this task

​
Headless Launch

# Claude headless with initial prompt
hcom claude -p "Fix all TypeScript errors"

# Or with --headless flag
hcom claude --headless --hcom-prompt "Run tests"

​
Launch with Specific Terminal

# Open in kitty tabs
hcom 2 claude --terminal kitty-tab

# Open in tmux sessions
hcom 3 gemini --terminal tmux

​
Launch with Custom Args

# Claude with specific model and agent file
hcom claude --model opus --agent reviewer

# Gemini with model override
hcom gemini -m gemini-2.5-pro

# Codex with sandbox disabled
hcom codex --sandbox off

​
Environment-Based Launch

# Set default tag for session
export HCOM_TAG=experiment-1
hcom 5 claude
# All get tag: experiment-1-*

​
Output

Successful launch prints: 
Started the launch process for 3 Claude agents
Names: luna, nova, kira
Batch id: batch_abc123
To block until ready or fail (30s timeout), run: hcom events launch

​
Exit Codes

​
0
success
All agents launched successfully
​
1
error
One or more launches failedCheck output for error details

​
Notes

Confirmation Gate: When launching from inside an AI tool with arguments or large batches (N > 5), hcom shows a preview and requires --go flag to proceed. This prevents accidental resource-heavy launches.
Hooks Installation: Hooks are automatically installed in ~/ (or $HCOM_DIR) on first launch. Remove with hcom hooks remove.
Terminal Detection: When HCOM_TERMINAL=default, hcom auto-detects kitty, wezterm, or tmux and uses appropriate spawn commands. For other terminals, set explicitly.
Argument Merging: Environment args (HCOM_*_ARGS) are merged with CLI args. CLI args take precedence for conflicting flags.
Max Count: Claude allows up to 100 simultaneous agents due to its stability in PTY mode. Other tools are limited to 10 to prevent resource exhaustion.

Build docs developers (and LLMs) love

Get started for freeTalk to us