conversation-reader

# Conversation Reader

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

## Quick Start

```bash
# 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

| Flag | Description |
|------|-------------|
| `--user` | Include user messages |
| `--assistant` | Include assistant messages |
| `--tools` | Include tool calls/results |
| `--last N` | Limit to last N items |
| `--output FILE` | Custom output path (default: `/tmp/{conversation_uid}.txt`) |
| `--json` | Output JSONL instead of XML (backwards compat) |

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

## Output Formats

### Default: Semantic XML

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

```xml
<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):

```json
{"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