# Claude Code Session Recovery on macOS # How to Run the Claude Code Session Recovery Toolkit on macOS *A step-by-step guide for Mac users—plus the fix that made the* `--state` *workaround unnecessary forever.* * * * ## Background If you've lost Claude Code session history on macOS after an app update, you're not alone. A silent bug in Claude Desktop has been wiping `.jsonl` conversation files during updates, leaving sessions showing "No messages yet" or disappearing from the sidebar entirely. The Anthropic issue thread ([#48334](https://github.com/anthropics/claude-code/issues/48334)) has been active, and a community member going by BasedGPT built an open-source recovery toolkit to diagnose and repair affected sessions: [claude-code-session-recovery](https://github.com/BasedGPT/claude-code-session-recovery). There's one problem: the toolkit was built and tested on Windows. Running it on macOS requires a workaround — or at least it did, until [PR #6](https://github.com/BasedGPT/claude-code-session-recovery/pull/6) landed native macOS path detection in the last remaining script. This guide walks you through running the toolkit on macOS end-to-end, with no workarounds needed. * * * ## What the Toolkit Does The toolkit has three main scripts, all read-only except when you explicitly pass `--apply`: * `diagnose.py` — scans your session metadata and `.jsonl` files, identifies which sessions are broken and why, and gives you a Diagnosis ID * `repair_session_metadata.py` — attempts to relink orphaned metadata files to their `.jsonl` transcripts (dry-run by default) * `find_missing_jsonls_in_backup.py` — searches backup locations for `.jsonl` files that are missing from your live projects directory * * * ## Prerequisites * macOS (any Apple Silicon or Intel Mac) * Python 3.x (comes pre-installed on macOS — run `python3 --version` to confirm) * Git — for git pull, OR you can download the code and use it manually * Claude Desktop installed at least once (so the session directories exist) * * * ## Step 1 — Quit Claude Desktop Fully This is critical before running any repair. Click the Claude icon in your **menu bar** → **Quit**. Verify it's fully stopped: ```bash ps aux | grep -i "Claude Desktop" | grep -v grep ``` If that returns nothing, you're clear to proceed. * * * ## Step 2 — Clone the Toolkit ```bash cd ~/Desktop git clone https://github.com/BasedGPT/claude-code-session-recovery cd claude-code-session-recovery ``` * * * ## Step 3 — Run the Diagnostic ```bash python3 tools/diagnose.py ``` As of [PR #6](https://github.com/BasedGPT/claude-code-session-recovery/pull/6) being merged, `diagnose.py` now auto-detects macOS paths natively — no `--state` flag or symlink fixture needed. You'll see output like this: ```plaintext DIAGNOSE -- Claude Code Desktop Session Recovery Tools ------------------------------------------------------------ Diagnosis ID : 0e7dfd9d Metadata : 10 files (4 with cliSessionId, 6 missing) JSONL files : 2 PROBLEM FOUND: Sessions appear in the session list but open with no conversation history PROBLEM FOUND: Session is in the session list but its conversation history is missing from disk ``` Note the **Diagnosis ID** — you'll need it in the next step. **What the output means:** * `Metadata X files` — total session metadata files found * `with cliSessionId` — sessions correctly linked to a `.jsonl` transcript * `missing` — sessions with no link (these show "No messages yet" in the UI) * `JSONL files` — actual conversation transcript files found on disk * * * ## Step 4 — Run the Repair (Dry-Run First) Always dry-run before applying anything: ```bash python3 tools/sessions/repair_session_metadata.py --diagnosis-id ``` Replace `` with the Diagnosis ID from Step 3. The output will show one of three states for each session: * `LINKED` — successfully matched to a `.jsonl` file, will be repaired * `REFUSED` — multiple possible `.jsonl` matches, too ambiguous to auto-repair * `ORPHAN` — no `.jsonl` file exists on disk to link to (data is gone) If you see sessions marked `LINKED`, you can recover those. If everything shows `ORPHAN`, the conversation files were deleted by the app update and are unrecoverable. **To apply the repair** (only if you saw `LINKED` sessions in the dry-run): ```bash python3 tools/sessions/repair_session_metadata.py --diagnosis-id --apply ``` * * * ## Step 5 — Check for Missing JSONLs in Backups ```bash python3 tools/sessions/find_missing_jsonls_in_backup.py ``` This scans Time Machine and common cloud sync locations (OneDrive, iCloud, Dropbox) for any `.jsonl` files that are missing from your live projects directory. If it finds matches, it will tell you which sessions are recoverable and from where. If you have a custom backup location, point it there: ```bash python3 tools/sessions/find_missing_jsonls_in_backup.py --backup /path/to/your/backup ``` * * * ## Step 6 — Reopen Claude Desktop Once you've run the repair, reopen Claude Desktop. Sessions that were successfully relinked should now show their conversation history again. * * * ## What If Everything Is Orphaned? If the toolkit confirms all your sessions are `ORPHAN` with `Repaired: 0` — as was my case — the `.jsonl` files were deleted outright by the app update. There is no recovery path. The toolkit is still useful in this situation: it gives you a confirmed diagnosis rather than uncertainty, tells you exactly which sessions are gone and when they were last active, and rules out any fixable metadata issue. * * * ## Prevent This From Happening Again Two things worth setting up immediately: **Automated daily backup of your Claude projects folder:** ```bash cat > ~/Library/LaunchAgents/com.claude.backup.plist << 'EOF' Label com.claude.backup ProgramArguments /bin/sh -c cp -r ~/.claude/projects/ ~/Desktop/claude-backup-$(date +%Y%m%d) StartCalendarInterval Hour 20 Minute 0 EOF launchctl load ~/Library/LaunchAgents/com.claude.backup.plist ``` **Enable Time Machine** with an external drive — Apple menu → System Settings → Time Machine → Add Backup Disk. It backs up hourly while your Mac is on and catches up on missed backups when the drive reconnects. * * * ## A Note on the macOS Fix When I first ran the toolkit, `find_missing_jsonls_in_backup.py` still had the old Windows-only hardcoded path: ```python APPDATA_CLAUDE_DIR = os.path.join( os.environ.get("APPDATA", os.path.expanduser("~")), "Claude" ) ``` `diagnose.py` and `repair_session_metadata.py` had already been updated with native macOS detection in commit `0609930`, but this script was missed. I submitted [PR #6](https://github.com/BasedGPT/claude-code-session-recovery/pull/6) which adds the same `_default_appdata_claude_dir()` pattern for consistency — it was merged the same day. If you cloned the toolkit before the merge, pull the latest: ```bash git pull origin main ``` And you're good to go — no fixture workaround needed on macOS anymore. * * * ## Useful Links * Anthropic GitHub issue: [anthropics/claude-code #48334](https://github.com/anthropics/claude-code/issues/48334) * Recovery toolkit: [BasedGPT/claude-code-session-recovery](https://github.com/BasedGPT/claude-code-session-recovery) * My first article covering the incident and broader lessons: [When AI Ate My Work](https://theranjana.hashnode.dev/when-ai-ate-my-work-a-claude-code-data-loss-incident-and-why-human-intelligence-still-matters-more-than-ever) * * * ## About the Author I'm Ranjan, a software & AI engineer who believes the best engineers are the ones who never stop being curious about how things work under the hood—AI era or not. If this guide helped you, let's connect: * 💼 [LinkedIn — linkedin.com/in/rpranjan11](https://linkedin.com/in/rpranjan11) * 🌐 [Portfolio — theranjana.com/portfolio](https://theranjana.com/portfolio)