Skip to main content

​
Overview

List active instances with status, unread counts, and metadata. Query single agents or view recently stopped instances.

​
Syntax

hcom list [NAME] [FIELD] [FLAGS]
​
NAME
string
Agent name or self for current identityWhen provided, shows single-agent details
​
FIELD
string
Extract specific field (requires NAME)Available fields: name, status, session_id, directory, tool, transcript_path, parent_name, agent_id

​
Flags

​
--json
boolean
Output as JSON arrayFull listing or single-agent object
​
-v, --verbose
boolean
Show detailed info (session_id, directory, bindings, transcript, etc.)
​
--names
boolean
Output only names, one per lineUseful for scripting
​
--sh
boolean
Shell export format (requires NAME)Outputs export HCOM_INSTANCE_NAME=... statements
eval "$(hcom list self --sh)"
echo $HCOM_INSTANCE_NAME
​
--format
string
Custom format template with {field} placeholders
hcom list --format '{name} {status}'
Available fields: name, status, status_context, status_detail, status_age_seconds, description, unread_count, headless, session_id, directory, parent_name, agent_id, tool, base_name, hooks_bound, process_bound, transcript_path, background_log_file, created_at, tag, launch_context
​
--stopped
boolean
Show recently stopped instances from life eventsDefault: last 20Use with --all or --last N to control count
​
--all
boolean
With --stopped: show all stopped instances (no limit)
​
--last
number
With --stopped: limit to last N (default: 20)

​
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

​
Tool Labels

Binding state encoded in case/asterisk:
  • [CLAUDE] - PTY + hooks (hcom-launched)
  • [claude] - Hooks only (vanilla tool)
  • [CLAUDE*] - PTY only (no hooks bound)
  • [claude*] - No binding (ad-hoc mode)
Same pattern for GEMINI, CODEX, OPENCODE, AD-HOC.

​
Examples

​
Full Listing

hcom list
Output: 
Your name: luna

[CLAUDE]   ▶ luna                now: processing
[GEMINI]   ◉ nova                listening since 2m
[CODEX]    ■ kira +3             3s ago: approval: bash command
[OPENCODE] ◦ zeus [headless]     unknown

Recently stopped (10m): apollo, athena
  -> hcom list --stopped [name]

​
Verbose Listing

hcom list -v
Output: 
Your name: luna

▶ luna                now: processing
    session_id:   sess_abc123
    tool:         claude
    created:      5m ago
    directory:    ~/my-project
    bindings:     hooks, pty
    transcript:   ~/.claude/sessions/sess_abc123/transcript.jsonl

◉ nova                listening since 2m
    session_id:   sess_def456
    tool:         gemini
    created:      10m ago
    directory:    ~/my-project
    bindings:     hooks
    transcript:   ~/.gemini/sessions/sess_def456.json

​
Query Self

hcom list self
# Output: luna

hcom list self status
# Output: active

hcom list self --json
# Output: {"name":"luna","session_id":"sess_abc123","status":"active",...}

​
Query Named Agent

hcom list nova
# Output:
# nova:
#   Status: listening
#   Directory: ~/my-project
#   Session: sess_def456

hcom list nova directory
# Output: ~/my-project

​
Names Only

hcom list --names
# Output:
# luna
# nova
# kira

​
JSON Output

hcom list --json | jq '.[] | select(.status == "listening") | .name'
# Output: nova

​
Custom Format

hcom list --format '{name} ({tool}) - {status}'
# Output:
# luna (claude) - active
# nova (gemini) - listening
# kira (codex) - blocked

​
Shell Exports

eval "$(hcom list self --sh)"
echo $HCOM_INSTANCE_NAME
# Output: luna

echo $HCOM_SID
# Output: sess_abc123

​
Stopped Instances

# Recent stopped (last 20)
hcom list --stopped

# All stopped
hcom list --stopped --all

# Last 50
hcom list --stopped --last 50

# Specific stopped agent
hcom list --stopped luna
Output (recent): 
Stopped instances (last 20):

  apollo (claude tag:dev) 5m ago  [self by:apollo]
  athena (gemini) 10m ago  [external by:luna]

  --all: show all  |  --last N: show last N
  Details: hcom list --stopped <name>
  Resume:  hcom r <name>
Output (specific): 
Stopped: apollo
  Time:       2026-03-04T10:23:45Z
  By:         apollo
  Reason:     self
  Tool:       claude
  Tag:        dev
  Directory:  ~/my-project
  Session:    sess_abc123
  Transcript: ~/.claude/sessions/sess_abc123/transcript.jsonl

  Resume: hcom r apollo

​
Exit Codes

​
0
success
Success
​
1
error
  • Named agent not found
  • Field not found
  • Identity resolution failed (for self)
  • Database query failed

​
JSON Schema

Full listing (--json) returns array of objects: 
[
  {
    "name": "luna",
    "status": "active",
    "status_context": "tool:Bash",
    "status_detail": "ls -la",
    "status_age_seconds": 3,
    "description": "processing",
    "unread_count": 0,
    "headless": false,
    "session_id": "sess_abc123",
    "directory": "/Users/anno/my-project",
    "parent_name": null,
    "agent_id": null,
    "background_log_file": null,
    "transcript_path": "/Users/anno/.claude/sessions/sess_abc123/transcript.jsonl",
    "created_at": 1709550000.0,
    "tag": null,
    "tool": "claude",
    "base_name": "luna",
    "hooks_bound": true,
    "process_bound": true,
    "launch_context": {
      "terminal_preset": "kitty",
      "pane_id": "123"
    }
  }
]

​
Notes

Unread Counts: Shown as +N suffix when agent has unread messages. Based on last_event_id cursor.
Listening Since: For idle agents in listening status for ≥60s, shows duration (listening since 2m).
Subagent Timeout: For subagents idle in listening status with less than 10s remaining before timeout, shows countdown (⏱ 5s).
Remote Badge: Instances from other devices (via relay) show [remote] suffix. Cannot be stopped locally.
Headless Badge: Background instances show [headless] suffix. Check background_log_file for logs.
Stale Cleanup: List automatically cleans up stale placeholders and instances idle >1h.
Multiple Tools: Tool prefix only shown when >1 tool type is active. Binding state encoded in case/asterisk.

Build docs developers (and LLMs) love

Get started for freeTalk to us