Read agent transcripts to understand what they’ve done, review their decisions, and share context between agents. Transcripts show the full conversation history with tool usage and file edits.
Basic Transcript Reading
View Recent Exchanges
hcom transcript @luna
# Shows last 10 exchanges
#15
User: Fix the authentication bug
Action: I'll check the auth flow first...
Files: src/auth.py, src/middleware.py
Tools: Read(2), Edit(1)
#16
User: Run the tests
Action: Running pytest...
Tools: Bash(1)
Specific Exchange Range
hcom transcript @luna 5 # Just exchange #5
hcom transcript @luna 5-10 # Exchanges 5 through 10
hcom transcript @luna --range 5-10 # Flag form
Limit Results
hcom transcript @luna --last 20
# Shows last 20 exchanges
Detail Levels
Normal (Default)
Truncated output for overview:
Shows:
- User prompts (truncated)
- Agent responses (truncated)
- File names
- Tool counts
Full
Complete text, no tool details:
hcom transcript @luna --full
- Complete user prompts
- Complete agent responses
- File names
- Tool counts
Detailed
Complete text + tool I/O:
hcom transcript @luna --detailed
- Complete user prompts
- Complete agent responses
- File names and tool names
- Tool commands (Bash)
- File paths (Edit, Read, Write)
- Error indicators
Use —detailed when debugging or analyzing specific tool behavior. Use normal for quick overviews.
JSON Output
Machine-readable format:
hcom transcript @luna --json
[
{
"position": 15,
"user": "Fix the authentication bug",
"action": "I'll check the auth flow first...",
"files": ["src/auth.py", "src/middleware.py"],
"timestamp": "2026-03-04T10:30:45Z",
"tools": [
{"name": "Read", "is_error": false},
{"name": "Edit", "is_error": false, "file": "src/auth.py"}
]
}
]
Timeline View
See all agents’ activity chronologically:
Output:
2026-03-04 10:30:45 [luna] #15: Fix the authentication bug
2026-03-04 10:32:12 [nova] #8: Review the PR changes
2026-03-04 10:33:01 [luna] #16: Run the tests
hcom transcript timeline --full --last 20
Search Transcripts
Search across all agent transcripts:
hcom transcript search "authentication"
src/auth.py:42: def authenticate_user(username, password):
luna #15: Fix the authentication bug
nova #23: Review authentication flow
Search Options
# Live agents only
hcom transcript search "pytest" --live
# All transcripts (including stopped agents)
hcom transcript search "database" --all
# Filter by agent type
hcom transcript search "build" --agent claude
# Limit results
hcom transcript search "error" --limit 10
# Exclude your own transcript
hcom transcript search "test" --exclude-self
Transcript Sharing
Share transcript ranges with other agents:
Reference in Messages
hcom send @nova -- Read my transcript range 5-10 for context on the auth bug
Bundle with Context
hcom send @nova \
--transcript "10-15:detailed" \
--description "Auth bug context" \
-- Review my approach and suggest improvements
Understanding Transcript Structure
Exchanges
Each exchange consists of:
- User prompt - What you asked the agent to do
- Agent action - The agent’s response and reasoning
- Tools used - Which tools the agent called
- Files touched - Files read, edited, or written
- Errors - Any tool errors or failures
Exchange Numbers
Exchange numbers are sequential starting from 1:
hcom transcript @luna
# #1, #2, #3, ...
hcom transcript @luna 10-15
# Shows exchanges during that work session
Timestamps
Each exchange has a timestamp:
#15 @ 2026-03-04T10:30:45Z
hcom events --after 2026-03-04T10:30:00
Tools: Bash(3), Read(5), Edit(2)
Tools:
Bash: pytest tests/
Bash: git status
Read: src/auth.py
Edit: src/auth.py:42 (success)
Tools:
Bash: npm install (ERROR)
Edit: src/db.py:123 (ERROR)
Practical Examples
Review Work Session
hcom transcript @luna --range 20-30 --detailed
# See exactly what luna did in exchanges 20-30
Debug Errors
hcom transcript search "ERROR" --agent luna --limit 5
# Find recent errors in luna's transcript
Compare Approaches
hcom transcript @luna --range 10-12 --json > luna.json
hcom transcript @nova --range 15-17 --json > nova.json
diff luna.json nova.json
Share Context
hcom send @reviewer \
--transcript "20-25:full" \
--title "Code Review Context" \
--description "My implementation of the auth fix" \
-- Please review this approach
- Claude Code:
~/.claude/projects/*/transcript.jsonl
- Gemini CLI:
~/.gemini/transcript.json
- Codex CLI:
~/.codex/transcript.jsonl
- OpenCode:
~/.config/opencode/opencode.db
All formats are normalized to the same structure.
Transcript Lifecycle
Active Sessions
Transcripts update in real-time:
hcom transcript @luna
# Shows all exchanges up to now
Stopped Agents
Transcripts remain readable:
hcom stop luna
hcom transcript @luna
# Still accessible
Archived Sessions
After hcom reset, transcripts move to archive:
hcom archive # List archives
hcom archive 1 agents # Show archived agent names
Troubleshooting
Transcript Not Found
Check if agent is registered:
Verify transcript path:
hcom list luna --json | jq .transcript_path
Exchange Numbers Don’t Match
Exchange numbers are per-session. After resume/fork:
hcom r luna
# Continues from where it left off
Large Transcripts
Use ranges to avoid loading everything:
hcom transcript @luna --last 20 # Last 20 only
hcom transcript @luna 100-110 # Specific range
Best Practices
- Use normal detail for quick scans
- Use —full when sharing context
- Use —detailed for debugging tool issues
- Use —json for programmatic analysis
- Reference ranges instead of copying full text
Transcripts can contain sensitive data (API keys, credentials) if agents used them. Be careful when sharing transcript excerpts.
Next Steps