# script: extract-transcripts

**Location:** `claude-foundations/scripts/extract-transcripts.py`  
**Symlinked to:** `~/.claude/scripts/extract-transcripts.py`

## Purpose

Manages the transcript backup tracking system. Registers pre-compaction JSONL backups, lists unprocessed ones per project, extracts readable conversation text for analysis, and marks entries as processed after a log is written.

## Usage

```bash
# Register a new backup (called by pre-compact-backup.sh hook)
python3 ~/.claude/scripts/extract-transcripts.py \
  --register BACKUP_NAME --session-id SESSION_ID --cwd PROJECT_CWD

# List unprocessed transcripts for a project (used by /log skill)
python3 ~/.claude/scripts/extract-transcripts.py --list /home/paul/dev/claude/projects/foo
# → compact JSON array of {backup, session_id, saved_at, path, exists}

# Extract readable conversation from one backup (used by /log Sonnet subagent)
python3 ~/.claude/scripts/extract-transcripts.py --extract BACKUP_NAME

# Mark all unprocessed backups for a project as done
python3 ~/.claude/scripts/extract-transcripts.py \
  --mark-all-processed /home/paul/dev/claude/projects/foo --log-file memory/log/YYYY-MM-DD.HHMMSS-transcripts.md
```

## How it works

- Tracking state lives in `~/.claude/transcript-backups/tracking.json`, keyed by backup filename
- Each entry: `{session_id, cwd, saved_at, processed, log_file, processed_at}`
- `--list` filters by `cwd == project_cwd` and `processed == false` — output is metadata only (no content), safe for skill pre-gathering
- `--extract` reads the JSONL, skips sidechain entries, extracts `user`/`assistant` message text, truncates per-message at 3000 chars
- Tool use blocks are summarised as `[tool: ToolName(key=...)]` rather than shown in full

## Gotchas

- `sys.exit(0)` inside a bare `except: pass` block is caught as SystemExit — always use specific exception types or `break` when early exit is needed inside exception handlers
- The JSONL entries for `type: "user"` without a `message` field (e.g., file-history snapshots) are skipped silently
- Old backups with `-auto` suffix (from before this system) are not in tracking.json and will never appear in `--list`