Claude Code Crashed and Took 12 Conversations With It. Here Is the Tool I Built.

9 minute read | Published April 26, 2026

Short answer: If you run Claude Code as a real workspace with multiple ongoing conversations, an iTerm or tmux crash will detach every one of them and leave you to reconstruct which UUID belongs to which project by hand. I built a free open-source tool called claude-resurrect that brings them all back in one command. It is on GitHub. macOS only for now.

Here is the situation that pushed me to build this. On a normal workday I have somewhere between 8 and 18 active Claude Code conversations open across iTerm tabs. One per project. Pricing on the Fig House short-term rental in one tab. The Mission Control dashboard branch in another. A blog draft for tamaraashworth.com in a third. Lead research for an Ashworth Strategy client in a fourth. And so on.

This is not bad hygiene. Each session is scoped to one specific topic, which is exactly how Claude Code is supposed to be used. I wrote about that in a separate post on running AI as a workspace. The problem is what happens when iTerm crashes, my Mac reboots, or tmux dies. Those conversations are technically still on disk, because Claude Code writes every turn to a jsonl file, but the mapping between "tab" and "conversation" is gone. I am left looking at a list of UUIDs in a directory and trying to remember which one was the Fig House pricing thread.

I built claude-resurrect to make that recovery one command. Below is what it does, how it works, how to install it, and the honest tradeoffs.

What Actually Happens When Claude Code Crashes

To understand the fix, you need to understand the failure clearly.

Every time you open a Claude Code conversation, it gets a UUID. Something like 46f4e25f-3d84-4183-afb7-c4cad9cec678. That UUID becomes the filename of a jsonl file at ~/.claude/projects/[encoded-cwd]/[UUID].jsonl. Every message you send and every response Claude generates appends to that file in real time. So even if your machine hard-crashes mid-message, every completed turn up to that point is on disk.

What is not on disk in any easily recoverable way is the relationship between your terminal tabs and those UUIDs. If you had eight Claude Code tabs open in iTerm, your Mac knows there were eight processes running, but once those processes die, the only record of which tab was which conversation is in your head.

You can still resume any individual conversation by running claude --resume and picking from a list. Claude Code will show you a chronological list of recent sessions. But if you have 50 sessions across 6 different working directories accumulated over the last month, finding the right one for the right tab is a 30-minute manual archaeology task. I have done this task more times than I want to admit.

The native tooling assumes you will close conversations cleanly with /exit and start fresh. It does not assume you will be running 12 of them simultaneously across multiple ongoing projects, the way a serious operator actually uses the tool.

Why "Just Use --resume" Is Not Enough

The first instinct most people have is to bookmark UUIDs somewhere. Write them in a Notion page. Pin them in a document. That works for two or three conversations. It collapses fast at any kind of scale.

The problem is not just the count. It is that the right UUID for any given tab changes constantly. Every time you start a fresh session in a tab, the old UUID stops being the right one. Maintaining that mapping by hand is the kind of low-grade administrative tax that quietly eats hours over the course of a month.

The other instinct is to set up tmux-resurrect, which is a fantastic open-source tmux plugin that saves and restores your full tmux state across reboots. It captures session names, window names, working directories, the last screen of pane output, and the names of running processes. After a reboot, it can rebuild your tab structure with one command.

The catch is what tmux-resurrect does with running processes. It saves the command name (claude) and the command-line flags. On restore, it re-runs that command. The result is a fresh empty Claude Code session in each tab, not the conversation you were having before. The structure comes back. The conversation does not.

So the gap is specific. tmux-resurrect handles tabs perfectly. Claude Code handles conversation persistence perfectly. Nobody had built the bridge.

What I Built (claude-resurrect)

claude-resurrect is a small package that combines three things into one command:

• tmux-resurrect plus tmux-continuum. Auto-saves your tmux state to disk every 15 minutes. Restores tab structure and pane scrollback on reboot.
• A Python tracker. Runs every two minutes via macOS launchd. Maps each tmux session to the Claude Code conversation UUID that is currently active in it.
• A resurrect command. Reopens iTerm tabs via AppleScript, names them, attaches each to its tmux session, and re-launches the right Claude Code conversation in each.

After an iTerm crash or a Mac reboot, the entire recovery is one word in your terminal:

resurrect

That is the whole interface. One command opens every saved tab and reattaches every Claude Code conversation. You go from a blank desktop to your full workspace in under 30 seconds.

How It Works Under the Hood

For the technically-curious, and for clients who want to understand what they are running on their machine, here is the actual mechanism.

Claude Code already writes a metadata file for every running session at ~/.claude/sessions/[PID].json. Each file looks roughly like this:

{
  "pid": 5749,
  "sessionId": "46f4e25f-3d84-4183-afb7-c4cad9cec678",
  "cwd": "/Users/openclaw",
  "startedAt": 1776947339991,
  "kind": "interactive"
}

This is the source of truth I needed. The tracker walks every running Claude Code process, reads its metadata file, and pairs it with a tmux session by matching teletype (tty) values. Every iTerm tab attached to tmux has a tty. Every Claude Code process running in a tab inherits that tty. So if I find a claude PID on tty ttys021 and a tmux pane on the same ttys021, I have a deterministic mapping between that tmux session and that conversation UUID.

The mapping gets written to a local JSON file at ~/.claude-resurrect/cc-session-map.json. The launchd job re-runs the tracker every two minutes, so the map stays current within a small window even as you start and end conversations.

When you type resurrect, the script reads that map. For each detached tmux session, it uses iTerm2 AppleScript to open a new tab, set the tab title, and attach to the right tmux session. Then for any pane that does not currently have claude running (which is true after a reboot, because tmux-resurrect was configured to skip claude), it sends the command cd [original cwd] && claude --resume [UUID] to that pane. Claude Code starts up exactly where it left off.

Nothing leaves your machine. There is no cloud component, no API call, no telemetry. The tracker reads files on your local disk and writes a local file. The resurrect command runs AppleScript locally. This was important to me. I run client conversations through Claude Code regularly, and I would not install a third-party tool that exfiltrated any of that.

The Three-Layer Recovery Model

The mental model for what survives a crash and what does not is cleaner once you separate the layers.

Layer 1: The conversations themselves. Claude Code writes every completed turn to a jsonl file as it happens. Even a hard crash mid-message preserves everything up to the last completed response. This layer is not affected by the tool. It already worked.

Layer 2: The tab structure. tmux-continuum auto-saves your tmux state to disk every 15 minutes. After a reboot, it can rebuild the entire tab structure (session names, window names, working directories, last screen of output) from the most recent save. This layer is what tmux-continuum already provides. The tool just configures it correctly.

Layer 3: The mapping between layers 1 and 2. This is what nobody had built. Without it, you can have your conversations on disk and your tab structure on disk and still be unable to put them back together. The tracker plus the resurrect command is this missing layer.

The point of the model is that recovery is not about saving more, it is about reconnecting things that are already saved. Claude Code already knows your conversations. tmux already knows your workspace. claude-resurrect is just the bridge.

What Survives a Crash and What Does Not

Honest accounting matters. Here is what holds up and what does not.

Survives

• Every Claude Code conversation in full, up to the last completed turn before the crash. Worst case you lose a partially-typed message you had not sent yet.
• Tab structure and working directories as of the most recent tmux-continuum save (every 15 minutes by default).
• Last screen of pane output, captured at save time. Useful for orienting yourself when you reopen a tab.

Does not survive

• Long-running jobs inside panes. Playwright sessions, dev servers, polling loops, npm run scripts. tmux-resurrect re-spawns the binary by name on restore, but the job state is gone. You will need to restart these manually.
• Tab changes from the last 15 minutes. If you opened a brand-new tab and the Mac died five minutes later, that new tab will not be in the restore. tmux-continuum had not saved yet.
• Brand-new Claude sessions from the last two minutes. The tracker had not seen them yet, so resurrect will not auto-resume those specific tabs. You can pick them up manually with /resume.

None of these are dealbreakers in practice. Long-running jobs are usually visible in tmux scrollback so you know to restart them. The 15-minute window for new tabs is rarely material. And if you really care about a brand-new conversation, you can manually save tmux state with tmux run-shell ~/.tmux/plugins/tmux-resurrect/scripts/save.sh before walking away from your machine.

How to Install

One command from a fresh terminal:

curl -fsSL https://raw.githubusercontent.com/tamara-elaine/claude-resurrect/main/bootstrap.sh | bash

That clones the repo to ~/.claude-resurrect, runs the installer, and sets up everything. The installer is idempotent, which means safe to re-run. It does six things:

1. Installs TPM (the tmux plugin manager) if it is not already there.
2. Installs tmux-resurrect and tmux-continuum.
3. Adds a managed configuration block to your ~/.tmux.conf.
4. Drops the resurrect and tracker scripts under ~/.claude-resurrect/bin/.
5. Adds a resurrect alias to your ~/.zshrc or ~/.bashrc.
6. Installs a launchd job that runs the tracker every two minutes.

Requirements: macOS, iTerm2, tmux (brew install tmux if you do not have it), Claude Code on your PATH, and Python 3 at /usr/bin/python3 which ships with macOS by default. The repo and full source are at github.com/tamara-elaine/claude-resurrect.

When You Should Install This (and When to Skip)

This is for a specific kind of user. Be honest with yourself about whether that is you.

Install if:

• You run Claude Code daily across multiple ongoing projects.
• You have ever lost context to a crash and felt the pain of reconstructing which UUID belonged to which project.
• You want your AI workflow to feel like a workspace, not a fresh start every morning.

Skip if:

• You use Claude Code occasionally for one-off tasks. The standard /exit-when-done discipline is enough.
• You strictly run one session at a time. You do not have a mapping problem to solve.
• You are not on macOS. The tool currently depends on launchd and iTerm2 AppleScript.

If you are running AI as a real workspace, the kind I have written about before, the operator-grade reliability layer matters. If you are still in occasional-user territory, the basic /exit hygiene is the right discipline first.

FAQ

Does claude-resurrect send any data anywhere?

No. Everything runs locally. The tracker reads files on your local disk and writes a local JSON file. The resurrect command uses local AppleScript and tmux. There is no network call, no cloud component, no telemetry. The full source is on GitHub for inspection.

Will this work with the Claude Code IDE extension?

The current version specifically targets the terminal version of Claude Code (the one launched with the claude command). The IDE extension manages its own session lifecycle and does not need this. If you mix both, the tool will simply ignore IDE sessions.

What happens if I install this and decide I do not want it?

Run bash ~/.claude-resurrect/uninstall.sh. That removes the launchd job, the alias from your shell config, and the managed block from your tmux config. It leaves the tmux plugins in place since they are useful on their own, and it leaves the package directory so you can reinstall later if you want.

Is this going to work on Linux?

Not yet. The current version assumes macOS because it uses launchd for the periodic tracker and iTerm2 AppleScript for opening tabs. A Linux port would need a systemd timer instead of launchd and a different terminal automation layer (likely tmux's own scripting since most Linux operators use tmux directly without iTerm). I am open to pull requests on the repo if anyone wants to work on this.

What if I do not use tmux at all?

Then this tool is not for you, at least not yet. The whole architecture is built on tmux as the structural layer. Without tmux you do not have the persistence framework that this tool extends. If you are running Claude Code in plain iTerm tabs without tmux, the bigger upgrade is to start using tmux first.

Can I use this for client work?

Yes. The license is MIT, so you can install it on any machine you operate, including client machines. If you build AI workflows for clients and you are tired of debugging "Claude Code lost my session" tickets, this solves that ticket category permanently.

Final Thought

Tools like this are small. The whole package is 6 KB. The mechanism is plain Python, AppleScript, and tmux configuration. Nothing in it is novel from a computer science perspective.

What it represents matters more than what it is. If you run AI seriously, the friction of losing context to a crash compounds across every workday. Building the small tool that removes that friction permanently is the kind of operator move that adds up. If you find yourself thinking "this is one of those things AI can fix instead of me eating the cost," that instinct is the right one. That is the consulting work I do every day for clients running AI as real infrastructure.

If you install claude-resurrect and find a bug or want a feature, open an issue on the repo. I will see it.