Edit or delete messages in a Claude Code session

Guide · August 2026 · ~4 min read

A session transcript is a plain text file — every user message, assistant reply, and tool result is one JSON line in ~/.claude/projects/<project-dir>/<session-id>.jsonl. That means you can edit it. People do this to remove a wrong turn the agent took, redact secrets before sharing a session, fix a tool output that failed for an environment reason, or trim a bloated session back to something usable.

The one rule

Records link through uuid → parentUuid, and tool calls pair with results through tool_use_id. Break either linkage and the session won't resume — you've traded an ugly message for a dead file. So:

• Delete a message → its children's parentUuid must be repointed to the deleted record's parent.
• Delete a tool call or result → delete them as a pair, or the survivor is orphaned and resume fails.
• Edit text in place → safe. The ids live outside the message content; changing words changes nothing structural.

Why not just open it in a text editor?

You can, for a small file. Real sessions are tens of megabytes with one JSON object per line — no wrapping, no search across records, and one stray comma kills the whole file. The manual commands to find broken records are in the resume troubleshooting guide.

Editing with SessionPatch

1. Open the editor and load your session file — parsing runs in your browser, nothing uploads.
2. Click any card to inspect the raw record. Edit rewrites the message text; Delete removes the record and heals the parent chain automatically.
3. The doctor panel lists anything still broken (orphaned pairs, broken chains) with click-to-jump.
4. Export writes <name>.patched.jsonl. Verify with claude --resume, then replace the original.

Related

• Session appears lost instead of editable? See repairing a corrupted session.
• Old sessions vanish on their own? That's cleanupPeriodDays.