Overview hcom archive lists and queries archived sessions. Each time you run hcom reset, the current session is archived to ~/.hcom/archive/session-{timestamp}/ with a complete copy of the database.Usage hcom archive # List archived sessions hcom archive < N > # Query events from archive (1 = most recent) hcom archive < N > agents # Query agents from archive hcom archive < nam e > # Query by name prefix
Listing Archives Output: Archives: 1. session-2026-03-04_143022 127 events 4 agents 2. session-2026-03-03_091544 89 events 2 agents 3. session-2026-03-02_201133 234 events 6 agents
Archives are numbered newest-first. Use the number or name prefix to query.
Querying Events By Index hcom archive 1 # Most recent archive hcom archive 2 # Second most recent
By Name hcom archive session-2026-03-04_143022 hcom archive 2026-03-04 # Prefix match
With Filters hcom archive 1 --sql "type='message'" hcom archive 1 --last 50 hcom archive 1 --json
Options:
--sql "expr" - SQL WHERE clause for filtering--last N - Limit results (default: 20)--json - JSON output--here - Filter to archives from current directory
Querying Agents Output: name status directory transcript luna stopped ~/projects/myapp ~/.claude/transcripts/luna.jsonl nova stopped ~/projects/myapp ~/.claude/transcripts/nova.jsonl kira stopped ~/projects/backend ~/.gemini/transcripts/kira.jsonl
With Filters hcom archive 1 agents --sql "directory LIKE '%myapp%'" hcom archive 1 agents --json
Filtering by Directory Use --here to show only archives with agents from the current directory:
cd ~/projects/myapp hcom archive --here
This filters both the archive list AND queries:
hcom archive --here # Only archives with agents from ~/projects/myapp hcom archive 1 --here # Events from agents in ~/projects/myapp
SQL Queries Use --sql for advanced filtering:
hcom archive 1 --sql "type='message' AND instance='luna'" hcom archive 1 --sql "type='status' AND json_extract(data, '$.status')='blocked'" hcom archive 1 --sql "type='life' AND json_extract(data, '$.action')='stopped'"
Available Fields From events_v view:
Base: id, timestamp, type, instance msg_*: from, text, scope, sender_kind, delivered_to[], mentions[] status_*: val, context, detail life_*: action, by, batch_id, reason
Examples Messages only
From specific agent
Status changes
Life events
Combined filters
hcom archive 1 --sql "type='message'"
JSON Output Output: { "archives" : [ { "index" : 1 , "name" : "session-2026-03-04_143022" , "path" : "~/.hcom/archive/session-2026-03-04_143022" , "timestamp" : "2026-03-04_143022" , "size_bytes" : 245760 , "created" : 1709564222.0 , "events" : 127 , "instances" : 4 } ], "count" : 1 }
Event JSON [ { "id" : 1 , "timestamp" : "2026-03-04T14:30:22Z" , "type" : "message" , "instance" : "luna" , "data" : { "from" : "nova" , "text" : "Task complete" , "scope" : "mentions" , "mentions" : [ "luna" ] } } ]
Common Queries
Find messages to a specific agent
hcom archive 1 --sql "type='message' AND msg_delivered_to LIKE '%luna%'"
Find when an agent was stopped
hcom archive 1 --sql "type='life' AND instance='luna' AND life_action='stopped'"
Find all file edit events
hcom archive 1 --sql "type='status' AND status_context LIKE 'tool:Edit%'"
Find blocked/approval events
hcom archive 1 --sql "type='status' AND status_context='approval'"
Archive Structure Each archive contains:
~/.hcom/archive/session-{timestamp}/ hcom.db # Complete database snapshot hcom.db-wal # WAL file (if exists) hcom.db-shm # Shared memory (if exists)
The database is a full SQLite copy with:
All events (messages, status changes, lifecycle)
All instance records (names, directories, transcripts, sessions)
Message read receipts
Subscriptions
Tips Archives are created automatically by hcom reset. You don’t need to manually archive sessions.
Use --here when working on multiple projects to quickly find relevant archives.
Archives can be large. Use --last N to limit query results for performance.
Troubleshooting Archive not found If you get “Archive not found”, run hcom archive to see available archives:
hcom archive # List all hcom archive --here # List from current directory
Empty archive If an archive shows 0 events/instances, it was likely created when the database was already empty (e.g., running hcom reset twice in a row).
SQL errors If your SQL query fails, check:
Use single quotes for string values: type='message' not type="message"
Use <> instead of != for SQL negation
Use LIKE '%value%' for JSON arrays like delivered_to and mentions