conversation-reader

Conversation Reader

Extract conversation content with composable filters. Use for self-reflection, verification, and audit.

Quick Start

# Script path (plugin or fallback)
SCRIPT="$([ -f "${CLAUDE_PLUGIN_ROOT}/lib/extract_conversation.py" ] && echo "${CLAUDE_PLUGIN_ROOT}/lib/extract_conversation.py" || echo ~/.claude/lib/extract_conversation.py)"

# Conversation only (user + assistant text)
uv run python "$SCRIPT" "<conversation.jsonl>" --user --assistant

# Tool calls and results
uv run python "$SCRIPT" "<conversation.jsonl>" --tools

# Everything, last 50 items
uv run python "$SCRIPT" "<conversation.jsonl>" --user --assistant --tools --last 50

# JSONL format (backwards compat)
uv run python "$SCRIPT" "<conversation.jsonl>" --tools --json

Flags

At least one of --user, --assistant, --tools required.

Output Formats

Default: Semantic XML

Optimized for AI consumption. Each entry has semantic tag with index:

<user_1>
Fix the bug in config.py
</user_1>

<bash_2>
git status
→ On branch main
    modified: config.py
</bash_2>

<assistant_3>
I'll update the config file now.
</assistant_3>

<edit_4>
config.py
  'timeout=30' → 'timeout=60'
</edit_4>

<thinking_5>
Reviewing the change... confidence is high
</thinking_5>

--json: JSONL Format

One JSON object per line (backwards compatible):

{"role": "user", "text": "Fix the bug", "_id": "abc123"}
{"role": "assistant", "tool_name": "Bash", "tool_input": {...}}

Chunking

• Auto-chunks: Splits into ~20K token files when content is large
• IMPORTANT: Read each chunk in its entirety - the whole purpose of chunking is to create context-sized pieces. Don't try to grep or extract from chunks; load each one fully.

Truncation

When to Use