vicnaum/vics-agent-skills/ai-conversation-extractor

ai-conversation-extractor

Convert AI conversation transcripts (Claude Code, Codex CLI, ChatGPT/Gemini JSONL; Cursor IDE SQLite storage) to clean, readable Markdown files. Strips binary blobs (base64 images, PDFs — typically 95%+ of file size) while preserving all human-readable content: user messages, assistant text, thinking, tool calls, and tool results.

See scripts/README.md for full JSONL format documentation.

Supported Formats

Auto-detected from file content — no flags needed:

Usage

Run the script at scripts/extract.py (within this skill's directory):

# Single file — outputs .md alongside the .jsonl
python3 <skill-dir>/scripts/extract.py <file.jsonl>
 
# Single file with custom output path
python3 <skill-dir>/scripts/extract.py <file.jsonl> -o output.md
 
# All .jsonl in a directory
python3 <skill-dir>/scripts/extract.py <directory>
 
# Recursive (includes subdirectories)
python3 <skill-dir>/scripts/extract.py <directory> --recursive
 
# Messages-only view (user + final assistant response per turn, no tools/thinking)
python3 <skill-dir>/scripts/extract.py <file.jsonl> --ua-final-only
 
# Batch convert to a specific output directory
python3 <skill-dir>/scripts/extract.py <directory> --out-dir ./converted/
 
# Keep Codex environment context and boilerplate in messages-only mode
python3 <skill-dir>/scripts/extract.py <file.jsonl> --ua-final-only --keep-env-context --keep-agent-boilerplate

No external dependencies — uses only Python 3.12+ stdlib (json, re, pathlib, argparse, sqlite3).

Cursor IDE conversations

Cursor stores conversations in a global SQLite DB (cursorDiskKV table: composerData:<id> metadata rows + bubbleId:<composerId>:<bubbleId> message rows; old versions inline the conversation in composerData). Use scripts/cursor_extract.py (opens the DB read-only, safe with Cursor running):

# List all conversations (newest first): composerId, last-updated, message count, title
python3 <skill-dir>/scripts/cursor_extract.py --list [--limit 50]
 
# Find conversations whose content matches a regex (full DB scan — can take minutes on multi-GB DBs)
python3 <skill-dir>/scripts/cursor_extract.py --grep "AccessManager|rate.?limit"
 
# Extract specific conversations to Markdown (named <title-slug>-<id8>.md)
python3 <skill-dir>/scripts/cursor_extract.py <composerId> [<composerId>...] --out-dir ./converted/
 
# Extract everything / use a custom DB path (e.g. Linux/Windows)
python3 <skill-dir>/scripts/cursor_extract.py --all --out-dir ./converted/ --db <path/to/state.vscdb>

Output uses the same Markdown conventions as extract.py. Notes: per-message timestamps are not stored by Cursor (only conversation-level created/updated times, used for frontmatter and file mtime); tool results in very recent Cursor versions may live in encrypted blobs and show as tool calls without results.

CLI Flags

What Gets Stripped

• Base64-encoded images and documents (biggest savings)
• <system-reminder> tags injected by the tool
• file-history-snapshot records (editor state backups)
• progress records (hook events)
• system records (turn durations, metadata)
• Meta messages (isMeta: true, like /init injections)
• Line-number prefixes from file reads ( 123→)

What Gets Preserved

• User text messages (full)
• Assistant text responses (full)
• Assistant thinking blocks (truncated at 3000 chars, in <details> tags)
• Tool calls (name + JSON input, truncated at 4000 chars)
• Tool results (text content, full; no truncation)
• Image/document placeholders (e.g., *[attached document: application/pdf]*)
• Error results from rejected tool uses
• Per-message timestamps (Claude Code format only)
• Source file metadata (YAML frontmatter) and filesystem mtime (output .md matches source .jsonl mtime for natural sort-by-date)

Output Format

• YAML frontmatter: source, modified (ISO 8601) for parseable metadata
• Filesystem: Output .md file's modification time is set to match the source .jsonl, so ls -t or Finder sort-by-date preserves conversation order
• Markdown with ## User / ## Assistant headings separated by ---. Per-message timestamps shown as *2026-02-09T23:51:07Z* when available (Claude Code format). Tool calls formatted as **Tool: \Name\** with JSON code blocks. Tool results as **Result** (\id\): with code blocks.