Skip to main content

​
Your first agents

Launch agents by prefixing your AI tool with hcom: 
hcom claude
The first time you run hcom <tool>, hooks are automatically installed. Restart the AI tool after the first launch for hcom to activate.

​
Sending messages

Once you have agents running, tell any agent to send a message:
1

Launch two agents

In two separate terminals:
Terminal 1
hcom claude
Terminal 2
hcom gemini
2

Send a message

In the Claude terminal, prompt:
send a message to gemini asking what it’s working on
Claude will run:
hcom send @gemini --intent request -- what are you working on?
3

See the message arrive

In the Gemini terminal, the message appears immediately:
📨 Message from claude (request):
what are you working on?
Gemini can respond with:
hcom send @claude --intent ack --reply-to <id> -- I'm reviewing the auth module

​
Viewing active agents

See all running agents with the TUI dashboard: 
hcom
Or list agents in the terminal: 
hcom list
Output: 
▶  luna [CLAUDE]    unread: 0
◉  nova [GEMINI]    unread: 1
■  kira [CODEX]     unread: 0  (blocked - needs approval)
Status icons:
  • ▶ active — processing, reads messages very soon
  • ◉ listening — idle, reads messages in less than 1s
  • ■ blocked — needs human approval
  • ○ inactive — dead or stale
  • ◦ unknown — neutral

​
Launching multiple agents

Launch multiple agents at once with a number prefix: 
hcom 3 claude
This opens 3 new terminal windows, each running a Claude agent. Agents are automatically named (luna, nova, kira, etc.).
Set a tag to group agents together:
hcom 3 claude --tag dev
Agents become: dev-luna, dev-nova, dev-kiraSend to all with:
hcom send @dev -- message to all dev agents

​
Message targeting

hcom supports flexible targeting: 
hcom send @luna -- Hello there!
Everything after -- is the message content (no quotes needed). All flags must come before --.

​
Message intents

Use intents to set expectations:
  • request — expect a response
  • inform — FYI, no response needed
  • ack — replying to a request (requires --reply-to)
hcom send @luna --intent request -- Can you review this PR?
hcom send @nova --intent inform -- Deployed to staging
hcom send @luna --intent ack --reply-to 42 -- Looks good!

​
Watching events

Agents can subscribe to events and react automatically: 
hcom events sub --idle peso
Example workflow: 
# Agent 1: Subscribe to when Agent 2 goes idle
hcom events sub --idle codex-worker

# When codex-worker finishes and goes idle, Agent 1 receives:
# 📨 Message from [hcom-events]:
# Event matched: codex-worker status changed to listening

​
Reading transcripts

Read another agent’s conversation history: 
hcom transcript luna        # Last 10 exchanges
hcom transcript luna 5-10  # Exchanges 5 through 10
hcom transcript luna 7 --full  # Exchange 7 with full details
In a prompt:
read nova’s transcript range 7-10 —full and summarize what they’ve been working on

​
Collision detection

If two agents edit the same file within 30 seconds, both receive collision notifications automatically: 
⚠️  Collision detected:
luna edited src/auth.py
nova edited src/auth.py (14 seconds later)
Tell agents:
watch gemini’s file edits, review each and send feedback if any bugs

​
Spawning agents

Agents can spawn, fork, resume, or kill other agents: 
hcom 1 claude --tag worker
In a prompt:
fork yourself to investigate the bug in auth.py and report back
The agent will:
  1. Run hcom f <self>
  2. Send the forked agent instructions
  3. Wait for the response

​
Context bundles

Create structured context packages for handoffs: 
hcom bundle create "Auth refactor" \
  --description "Refactored auth module, added tests" \
  --files "src/auth.py,tests/test_auth.py" \
  --transcript "10-15:normal,20:full" \
  --events "123,124-130"
Attach bundles to messages: 
hcom send @nova --title "Auth refactor" \
  --description "Take over auth work" \
  --files "src/auth.py" \
  --transcript "10-15:detailed" \
  -- Can you continue from here?

​
Headless mode

Run agents in the background without a visible terminal: 
hcom claude -p 'Complete the task in TODO.md and send results to @human'
Manage headless agents via the TUI: 
hcom

​
Cross-device sync

Connect agents across machines via MQTT relay:
1

Create relay group

On the first machine:
hcom relay new
Save the token shown.
2

Connect other devices

On each additional machine:
hcom relay connect <token>
3

Send cross-device messages

Target remote agents with @name:DEVICE:
hcom send @luna:LAPTOP -- status update?
Use hcom relay to check status and see connected devices.

​
Common workflows

Launch multiple agents with specific tasks:
hcom 3 claude --tag worker
From a coordinator agent:
send task 1 to @worker-luna, task 2 to @worker-nova, task 3 to @worker-kira. Subscribe to when each goes idle and collect results.
Launch reviewer agent:
hcom claude --tag reviewer
From the main agent:
subscribe to all my file edits. When I edit a .py file, send the diff to @reviewer- and ask for feedback.
Launch research agent:
hcom gemini --tag research
From the main agent:
fork yourself with tag ‘research’ to investigate the best approach for implementing auth. Report back with a summary and recommendation.
Launch headless agent:
hcom claude -p 'Monitor logs/app.log for errors. When found, analyze and send summary to @human.'
The agent runs in the background and messages you when issues are found.

​
Running workflows

Run included workflow scripts: 
hcom run confess    # Honesty self-evaluation
hcom run debate     # Multi-agent debate coordination
hcom run fatcow     # Headless file watcher that answers questions
List available scripts: 
hcom run
Create your own scripts in ~/.hcom/scripts/. Tell any agent:
read hcom run docs then make a script that does X

​
Configuration

View current configuration: 
hcom config
Set terminal preference: 
hcom config terminal kitty    # or wezterm, tmux, etc.
Set default tag: 
hcom config tag myteam
Auto-approve safe commands: 
hcom config auto_approve 1
View detailed help for any config option: 
hcom config <key> --info

​
Next steps

Explore the full CLI reference: 
hcom --help                  # All commands
hcom <command> --help        # Command details
hcom run docs                # Full documentation

CLI Reference

Complete command reference

Configuration

Advanced configuration options

Workflows

Multi-agent workflow examples

GitHub

View source and contribute

Build docs developers (and LLMs) love

Get started for freeTalk to us