Large base64 data in transcripts causes crash on startup

Summary

Claude Code crashes immediately on startup when a session transcript contains large base64-encoded data (e.g., from MCP servers like Playwright). The crash occurs even when NOT resuming that specific conversation - merely having the transcript in ~/.claude/projects/<projectpathslug>/ is enough to trigger it.

Environment

• OS: macOS (Darwin 24.6.0)
• Claude Code: Latest version

Steps to Reproduce

1. Use an MCP server that returns base64-encoded images (e.g., Playwright's screenshot functionality)
2. Take multiple screenshots in a session without using a subagent
3. Continue the session until the transcript grows large
4. Exit Claude Code
5. Attempt to start Claude Code again (even without resuming the problematic session)

Expected Behavior

Claude Code should start normally and handle large transcripts gracefully.

Actual Behavior

• Claude Code crashes immediately upon startup
• Only output is a "trap" line before exit
• No error message or indication of what failed
• No debug logs pointing to the problematic transcript

Root Cause Analysis

The issue stems from how base64-encoded image data accumulates in transcripts:

1. MCP servers like Playwright return screenshots as base64 data
2. Each screenshot must be sent to the LLM, making it part of the transcript
3. Even when context is compressed, the base64 representations remain in the transcript file
4. Each subsequent call that keeps images in context grows larger - observed growth from 4MB to 60MB+ per line
5. The problematic transcript reached 3.3GB total with individual lines exceeding 50MB

Evidence

• Transcript location: ~/.claude/projects/.../e6f27f6f-9002-487c-9bc3-ef6434850a6c.jsonl
• Total size: 3.3GB
• Individual line sizes: 4MB to 60MB+
• Extracted single problematic line: 4.7MB but they grew beyond 60MB, and I think the issue is overall size not per-line.

<img width="555" height="273" alt="Image" src="https://github.com/user-attachments/assets/20c5f4b3-7fd6-491b-b9b1-741de90ad11e" /> ... <img width="560" height="247" alt="Image" src="https://github.com/user-attachments/assets/4a5edd46-06fb-4a0c-b00f-4e4f25085900" />

I can get other lines if needed. This has been formatted by vscode into a readable json object over multiple lines but appears as a single line in the transcript.

problem-line.jsonl.zip

Suggested Fixes

Primary Fix

Similar to how the Bash tool handles large responses (forcing read from file), Claude Code internals should:

1. Evaluate lines in transcripts for base64 data
2. If found at any significant size, dump to a separate file
3. Replace inline data with a file reference in the transcript

Secondary Improvements

1. Better error messaging: When Claude crashes due to transcript issues, provide clear error output indicating:

• Which transcript file caused the issue
• What it tried to load and failed
• Where to find debug logs

1. Lazy loading: Consider not loading conversations that aren't being resumed. The 3.3GB file shouldn't impact memory for unrelated sessions.

1. Daemon architecture: Consider a daemon process to hold conversation data with IPC access, rather than loading transcripts into each Claude instance's memory.

Workaround

Delete the problematic transcript file from ~/.claude/projects/<projectpathslug>/. This was tested initially by moving the project folder to a new name, which starts fine, then putting it back and removing the 3.3GB jsonl file from that folder, and it still worked. If I was able to launch it (with a blank project folder), then move it back and use /resume, it also exits prematurely.

Additional Context

While MCP servers like Playwright could implement their own mitigations (similar to Bash tool), this is fundamentally a transcript management issue. Any user dropping images into Claude Code can experience this without MCPs - it's a real problem with how transcripts handle binary data.

---

This issue was drafted by Claude Code on behalf of @nsheaps based on their debugging session and analysis.