Last updated 13 October 2026
Recover work after a terminal crash
Restore the environment first
Your terminal window just vanished or your computer rebooted while you were in the middle of a complex refactor. This feels like a disaster because a coding agent is not just a text box; it is a stateful collaborator with a specific context window and a plan. When the process dies, you lose the immediate screen buffer and the active connection. However, the work itself is likely safe because of how the agent interacts with your local file system and how it stores its own history. You do not need to panic about losing the code the agent already wrote to your disk.
The first step is to open a new terminal window and navigate back to the root of your project directory. Claude Code stores its session data in a way that persists even if the terminal emulator itself fails. You should check if any background processes are still hanging from the previous crash. Sometimes a terminal crash leaves orphaned bash processes that might still hold locks on certain files. Use your system monitor or a process list command to ensure the environment is clean before you try to restart the agent.
Once you are back in the correct folder, you can verify your git status. Since the agent uses tools like Edit and Write to modify your files directly, you can see exactly what it finished before the crash. If you see half-finished edits, do not fix them manually yet. The agent is better at fixing its own interrupted work if you let it resume the context of the previous conversation. This prevents the agent from getting confused about why the file content changed outside of its known history.
Identify the interrupted session
Claude Code provides specific commands to help you get back to work without starting from scratch. If you were only working on one thing, you can use the command claude --continue. This command tells the agent to carry on with the most recent session found in that specific folder. It is the fastest path back to your work because it bypasses the need to look through a list of past interactions. It simply picks up the thread where it was cut off.
If you were juggling multiple tasks or if the crash happened a while ago, you might need a more precise approach. You should run the command claude --resume. This command does not just open the last session; it offers a list of earlier sessions for you to pick from. Each entry in this list represents a distinct conversation history. You can look at the timestamps and the initial prompts to identify which one was active when the terminal shut down. Picking the right session ensures the agent has the correct mental model of the task.
The resume list is essential when you have multiple developers or different automated tasks running in the same repo. It prevents you from accidentally resuming a session that someone else started or one that you abandoned days ago. Once you select the session from the list, the agent loads the conversation history into its memory. You will see the interface return, though the previous scrollback text from the crashed terminal window will not be visible. The agent remembers the conversation even if your terminal screen is blank.
Verify the state of the local files
After you resume the session, the agent needs to know the physical state of your project. A terminal crash can happen while the agent is in the middle of using the Write tool or the Edit tool. Use the Read tool or the Bash tool to inspect the files the agent was touching. You can simply ask the agent to check the status of the files it was just working on. It will use the Glob tool or the Grep tool to scan the directory and compare the current file content with its internal memory.
If the agent was in the middle of a multi-file refactor, some files might be inconsistent. You can use the /status command inside the session to see what the agent believes its current task is. This command provides a high-level view of the current progress and any pending items in the task list. If the agent looks confused, you can provide a new prompt explaining that a crash occurred. Tell it to verify that the last few edits were completed successfully before moving on to the next step.
The agent is capable of self-correction if it finds a half-written file. It might use the Edit tool to remove a syntax error it created during the crash or use the Write tool to finish a truncated file. Do not assume the agent knows it crashed. From its perspective, there was just a long pause between the last tool use and your next prompt. Clear communication at this stage prevents the agent from building new code on top of a broken foundation.
Navigate the session history list
The list provided by claude --resume is your primary tool for recovery. If you find that the session you resumed is not the right one, you can exit with Ctrl+C and try the command again. The history persists until you explicitly clear it. Each session is a record of the prompts you gave and the tools the agent used, such as WebSearch or NotebookEdit. This history is vital for maintaining the context window which allows the agent to understand complex project structures.
Sometimes a crash happens because of an out-of-memory error or a system-wide failure. In these cases, the session history is usually still intact because it is written to the user's home directory. You can use the command claude doctor to check the health of your installation if you find that sessions are not appearing in the list as expected. This utility checks for common configuration issues and ensures that the agent has the permissions it needs to read and write its own history files.
If you have lost track of which session belongs to which branch in your git repository, you can use the Bash tool to check your current branch after resuming. The agent can then help you align its internal task list with the actual state of your code. If the session history is too cluttered, you can use /clear to start fresh, but only do this if you are sure you do not need the previous context. Usually, resuming and then using /compact is a better way to clean up without losing the core logic of your work.
Synchronize the agent with your current progress
Once the session is active, use the /memory command to see what the agent has stored about your project. This shows you the current project summary and any key details the agent has gathered. If the crash happened during a long task, the agent might have lost the temporary plan it was holding in its immediate reasoning step. By checking the memory, you can see if you need to re-state the goals of the current task to get the agent back on track.
You may also want to use the /review command. This allows the agent to look over the changes made in the current session and provide a summary. This is a great way to catch mistakes that might have occurred during the terminal failure. If the /review command shows that the last few edits are missing or corrupted, you can explicitly ask the agent to re-run those specific steps. The agent can use the Write tool to overwrite any broken files with the correct versions from its history.
Communication is the key to a successful recovery. You should act as the supervisor. Tell the agent exactly what happened. A prompt like "The terminal crashed while you were editing the login controller, please check that file for syntax errors and resume the refactor" gives the agent a clear starting point. This prevents the agent from repeating work it has already finished or skipping over steps that were interrupted by the crash.
Manage context and costs after a restart
Resuming a session loads the entire conversation history back into the context window. This can be expensive if the session was already very long. Use the /cost command to see how much has been spent on the current session. If the session is reaching the limits of the context window or becoming too expensive to continue, you should use the /compact command. This summarizes the conversation so far and frees up space for new tokens while keeping the important information.
Monitoring your usage is especially important after a crash because you might end up repeating prompts or asking the agent to re-read files it has already processed. Use /usage to keep an eye on your token consumption. If you find that the agent is frequently re-reading the same large files, you can check your .claude/settings.json or the project-specific .claude/settings.json to see if you can optimize how the agent interacts with your codebase.
If you are worried about the cost of recovering a massive session, you can use /export to save the current conversation to a markdown file. This gives you a permanent record of what was done. You can then use /clear to start a fresh, cheaper session and paste the relevant parts of the exported log back to the agent as context. This manual approach is more work but it keeps your context window lean and focused on the immediate task at hand.
Build a persistent workspace for multiple agents
Managing multiple terminal tabs is often where the risk of a crash or a lost session begins. If you are working on a complex system with many microservices, you might have five different Claude Code sessions running at once. When a terminal emulator fails, it is hard to remember which tab was which. This is where a dedicated workspace manager becomes useful for maintaining your mental flow and project organization.
The adhdTerminal app provides a more stable way to run these sessions. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many Claude Code sessions side by side, with each one appearing as a tile on a wall. Every tile has a colour, a number, and a name, which makes it much harder to lose track of your work if your system or terminal emulator experiences a hiccup.
A major benefit of this setup is that tiles reopen in the same place after a restart and resume the same session automatically. The tiles show whether the agent is working, waiting for you, done, or idle. This visual feedback is a significant improvement over a standard terminal list. It also shows the last exchanges of the conversation and can display headlines the project publishes, helping you quickly regain your context after an interruption without having to manually run recovery commands.
Implement durable project instructions
To make your sessions more resilient to crashes, you should use a CLAUDE.md file in your project root. This file holds project instructions and serves as a permanent reference for the agent. If you have to restart a session, the agent will read CLAUDE.md to understand the coding standards, build commands, and architectural patterns of your project. This reduces the amount of context you have to manually provide every time you start or resume a session.
You can also use a CLAUDE.md file in a subdirectory to provide specific instructions for a certain part of the tree. This is helpful for large monorepos where different folders have different requirements. For global preferences that should apply to every project you work on, you can place a CLAUDE.md file in your home directory at ~/.claude/CLAUDE.md. These files act as a safety net, ensuring that even if a session is lost and you have to start a new one, the agent immediately knows how to behave.
Finally, check your hook events in the configuration. You can use hooks like SessionStart or SessionEnd to automate certain tasks, but be aware that a crash might prevent a SessionEnd hook from running. If you have custom logic tied to these events, you may need to manually trigger a cleanup or a status check. By combining robust project instructions with persistent session management, you can turn a terminal crash from a work-stopping event into a minor inconvenience.
Questions people ask
Will I lose the code changes if the terminal crashes while Claude is writing?
Usually, the changes are safe. Claude Code uses the Write and Edit tools to modify files directly on your disk as it works. You can verify the state of your files using git status or a file explorer immediately after the crash occurs.
How do I find a specific old session if I have dozens in my history?
Run the command claude --resume to see a list of your previous sessions. The list shows the time the session started and the initial prompt you used. This helps you identify the correct context to load back into the agent.
What should I do if the resumed agent seems confused about where it left off?
Use the /status command to see the agent's current task list and /memory to see its stored project summary. You can then send a prompt explaining the crash and asking the agent to verify the last few files it modified using the Read tool.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.