Launch AI agents (Claude Code, Gemini CLI, Codex, OpenCode) with built-in communication capabilities. When launched with hcom, agents automatically get hooks for instant message delivery and event tracking.
Basic Launch
Launch a single agent in the current terminal:
hcom claude
hcom gemini
hcom codex
hcom opencode
Launch Multiple Agents
Launch multiple agents at once by prefixing with a count:
hcom 3 claude # Opens 3 new terminal windows
hcom 2 gemini # Opens 2 Gemini instances
All launched agents can communicate with each other via hcom messages and see each other’s activity through events.
Launch Modes
Interactive Mode (Default)
Opens agents in new terminal windows:
hcom 3 claude --model opus
Headless Mode
Launch agents in the background with a prompt:
hcom claude -p "analyze the test failures"
hcom 3 claude -p "fix the auth bug" --output-format json
- Run completely in the background
- Process the prompt and stop when done
- Ideal for parallel task execution
hcom 3 claude -p "run the test suite"
hcom 3 claude --tag reviewers
reviewers-luna, reviewers-nova, reviewers-kira.
Address the entire group:
hcom send @reviewers -- "Review the PR changes"
Launch Options
System Prompts
Customize agent behavior with system prompts:
hcom claude --hcom-system-prompt "You are a code reviewer focused on security"
Initial Prompts
Provide an initial task for the agent:
hcom claude --hcom-prompt "Analyze the authentication flow"
Custom Terminal
Choose where new agents open:
hcom config terminal kitty # Use kitty terminal
hcom config terminal wezterm # Use wezterm
hcom config terminal tmux # Use tmux sessions
- kitty (split, tab, window modes)
- wezterm (split, tab, window modes)
- tmux (background sessions)
- Terminal.app, iTerm, Ghostty, alacritty
Resume and Fork
Resume a Stopped Agent
Resume a previously stopped agent by name:
hcom r luna # Resumes the 'luna' agent
Fork an Agent
Create a copy of an agent’s session (Claude only):
hcom f luna # Creates a fork of 'luna' with shared memory
- Explore alternative approaches
- Investigate bugs in parallel
- Create specialized reviewers
Forked agents share the same transcript/memory as the original but run independently.
Launch Coordination
When launching multiple agents, they’re grouped with a batch ID:
hcom 3 claude --tag workers --go
Started the launch process for 3 Claude agents
Names: workers-luna, workers-nova, workers-kira
Batch id: batch-1234567890
To block until ready or fail (30s timeout), run: hcom events launch
hcom events launch batch-1234567890
Working Directory
Launch agents in a specific directory:
cd ~/my-project
hcom claude # Launches in ~/my-project
hcom claude -C ~/my-project
Troubleshooting
Launch Fails
Check if hooks are installed:
Add hooks if missing:
Agents Not Communicating
Verify agents are registered:
Check recent activity:
Too Many Open Terminals
Use headless mode for background tasks:
hcom 5 claude -p "analyze the logs" --headless
Best Practices
- Use tags to organize agents by role (reviewers, testers, debuggers)
- Use headless mode for parallel batch processing
- Use resume to continue work without losing context
- Use fork to explore alternative solutions
Launching too many interactive agents (>10) can overwhelm your window manager. Use headless mode for large batches.
Next Steps