---

name: claude-history-restore version: 1.0.0 description: Restore a Claude Code conversation to an earlier local history point after compaction or unwanted turns. Use when a user wants to resume from before a compact summary, failed auth/model command, or accidental local command, while keeping backups and preserving the original session file. license: MIT compatibility: claude-code allowed-tools:

• Read
• Write
• Edit
• Bash

---

Claude history restore

Recover a Claude Code session by creating a new local session file that stops before the bad point. Do not edit the original session unless the user explicitly asks for that.

When to use

Use this when the user wants to:

• continue from before a compaction
• undo a few conversation turns after local undo no longer works
• remove failed auth, model, or slash command turns from the resume point
• preserve the full original transcript while creating a clean resume target

Workflow

1. Find the session.

Search Claude's local files for the session ID:

rg "SESSION_ID" ~/.claude ~/.claude.json

The main transcript usually lives at:

~/.claude/projects/<project-slug>/<session-id>.jsonl

2. Back up first.

Create a timestamped backup directory and copy the transcript plus relevant global files:

ts=$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.claude/backups/restore-$ts
cp ~/.claude/projects/<project-slug>/<session-id>.jsonl ~/.claude/backups/restore-$ts/
cp ~/.claude/history.jsonl ~/.claude/backups/restore-$ts/history.jsonl
cp ~/.claude.json ~/.claude/backups/restore-$ts/.claude.json

3. Inspect the transcript.

Find likely restore boundaries:

rg -n "This session is being continued|compact|oauth_org_not_allowed|/model|/compact" ~/.claude/projects/<project-slug>/<session-id>.jsonl

Print nearby records with line numbers, timestamps, UUIDs, parent UUIDs, type, role, and a short content preview. Pick the line before the unwanted compaction or turn.

4. Create a new session, not a modified original.

Copy records up to the chosen cutoff line into a new JSONL file. Replace only the top-level sessionId value with a fresh UUID. Keep all message UUIDs and parent UUIDs intact.

import json, uuid
from pathlib import Path

old = "SESSION_ID"
new = str(uuid.uuid4())
src = Path("/path/to/original.jsonl")
dst = src.with_name(new + ".jsonl")
cutoff = 1506

with src.open() as f, dst.open("w") as out:
    for i, line in enumerate(f, 1):
        if i > cutoff:
            break
        obj = json.loads(line)
        if obj.get("sessionId") == old:
            obj["sessionId"] = new
        out.write(json.dumps(obj, separators=(",", ":")) + "\n")

print(new)
print(dst)

5. Verify the restored file.

Check that the new file has the expected length and does not contain the unwanted latest compaction or error:

wc -l ~/.claude/projects/<project-slug>/<new-session-id>.jsonl
rg -n "unwanted text or timestamp" ~/.claude/projects/<project-slug>/<new-session-id>.jsonl

If the search returns older compactions, that can be fine. The important part is that the bad latest boundary is gone.

6. Give the resume command.

claude --verbose --dangerously-skip-permissions --resume <new-session-id>

Also give the backup path and state that the original session was not touched.

Rules

• Always back up before writing.
• Prefer creating a new session ID over editing the original file.
• Do not delete history or backups.
• Do not expose secrets from transcripts in the final answer.
• If gh, ssh, or other auth data appears in history, redact it in summaries.
• If the requested restore point is ambiguous, create two options: one conservative and one cleaner.
• Keep the final answer short: backup path, new session ID, resume command, and what was preserved.