Last updated 13 October 2026
Update Claude Code without losing data
Managing updates while tasks are running
You might feel hesitant to update Claude Code when you have a complex task half finished. A standard update command often feels like it might wipe your history or reset your configuration. You worry that the agent will forget the context of your current file edits or the specific instructions you placed in your project root. This anxiety is common because command line tools often handle global state and local state in ways that are not always transparent to the user. You do not want to lose the progress of a long debugging session just to get the latest features or bug fixes.
If you are in the middle of a session where the agent is currently using the Bash tool or writing to files, you should finish that specific turn first. Interrupting a process with the Escape key is generally safe for your data, but it is better to wait until the agent is idle. Once the agent is waiting for your input, you can safely exit the session by pressing Ctrl+C. This ensures that all file operations are complete and the session state is saved to your local database before you attempt to modify the binary files of the tool itself. Your session history is not stored inside the executable, so the update will not delete your past conversations.
The standard update procedure
The primary method to get the latest version is to use the built-in command specifically designed for this purpose. You type "claude update" in your terminal to start the process. This command is safer than manually trying to reinstall the package through a global package manager because it is aware of the specific environment requirements of the tool. It checks for the latest version and performs the necessary steps to replace the binary while leaving your configuration files untouched. This automated process handles the fetching of the new version and the cleanup of the old one without requiring you to manually navigate your file system.
You do not need to worry about your project files like CLAUDE.md when you run this command. The update process targets the executable parts of the tool rather than your working directory. If you have active sessions running in multiple terminals, you should close them before running the update to ensure that no file locks prevent the binary from being replaced. Once the command finishes, your environment is ready to use the new version immediately. The tool does not require a system restart, but you will need to start a new terminal session or restart your existing one to see the changes in effect.
Protecting your project context
Every project you work on likely has a CLAUDE.md file in the root directory. This file holds the project instructions and is the most important piece of context for the agent. When you update the CLI, this file remains exactly where it is. The agent reads this file every time you start a new session or continue an existing one. Because this file is part of your git repository, it is completely decoupled from the version of the CLI you are running. You can even have a CLAUDE.md in a subdirectory to apply specific rules to that part of the tree, and those will also persist through any update of the main tool.
The agent also looks for a CLAUDE.md file in your home directory at ~/.claude/CLAUDE.md for global instructions. This file is also safe from the update process. It is a good practice to back up these files occasionally if they contain complex instructions that you have spent a lot of time refining. However, the update command is designed to be non destructive. It only modifies the internal files used to run the agent logic and does not touch the markdown files you use to define your project rules or the custom slash commands you might have saved in the commands folder.
Validating the installation
After the update finishes, you should verify that everything is working as expected before diving back into a high stakes coding task. The command "claude doctor" is the official way to check the health of your installation. This command runs a series of diagnostic tests to ensure that the permissions are correct and that the tool can communicate with the necessary services. It checks if your login session is still valid and if the configuration files are readable. This is a critical step because an update can sometimes reveal underlying issues with your node environment or shell configuration that were hidden before.
If the doctor command reports any errors, it will usually provide a clear description of what is wrong. This might include issues with file permissions in your home directory or problems with your path. You should fix these issues before starting a new session to avoid crashes or unexpected behavior. If you notice that the tool is acting strangely after an update, you can also use the /doctor slash command from within an active session. This allows the agent to check its own health while it is running, which can be helpful if you suspect a problem with a specific tool like Bash or Read.
Monitoring active sessions
When you manage many projects at once, tracking which sessions need an update can become difficult. This is where adhdTerminal provides a clear benefit by showing you a wall of tiles representing every active session. You can see at a glance which project is working, which is idle, and which is waiting for your input. Before you run "claude update" on your main machine, you can look at the adhdTerminal wall to ensure no tiles are currently in the middle of a critical task that might be disrupted by a restart. The app is a native tool for macOS and Windows made by MINDBALANCER OU in Estonia and is not affiliated with Anthropic.
The app shows the last few exchanges of every conversation on each tile. This helps you decide if a session is at a good stopping point. Since tiles in adhdTerminal reopen in the same place after a restart and resume the same session, you can safely close the app, perform your CLI update, and then relaunch it. Each tile has a colour, a number, and a name, making it easy to organize your work by priority. You can even check the status of your wall from your phone using the free iPhone app, which mirrors the wall over an end to end encrypted link. This ensures you never lose track of a task even when you are away from your primary computer.
Configuring project overrides
Your configuration settings are another area where you might fear data loss. Settings for Claude Code live in several places, including .claude/settings.json in your project and ~/.claude/settings.json for your user account. These files store your preferences for permission modes, such as whether the agent should use bypassPermissions or stay in the default mode. The update process does not overwrite these files. If you have created a .claude/settings.local.json file for your own untracked overrides, that file will also remain untouched. This ensures that your specific workflow and safety preferences are maintained across versions.
If you have configured MCP servers in your .mcp.json file, these will also persist. The "claude mcp" command allows you to manage these servers, and your configurations are stored separately from the main executable. This is important because setting up MCP servers can involve complex paths and environment variables. You do not want to reconfigure these every time a new version of the CLI is released. By keeping these settings in standard JSON files within your project or home directory, the tool ensures that your environment remains stable and predictable even as the core logic of the agent evolves.
Restoring your workflow
Once the update is confirmed and the health check is passed, you can return to your work. You do not have to start over from scratch in a new folder. Using the command "claude --continue" or the shorter "claude -c" will immediately carry on the most recent session in your current folder. This is the fastest way to get back to work. If you were working on multiple different tasks in the same repository, you can use "claude --resume" or "claude -r" to see a list of earlier sessions. This allows you to pick exactly the right context to restore.
The ability to resume sessions is a core feature that relies on a local database of your conversation history. adhdTerminal makes this even easier by allowing each tile to resume its specific session automatically. You do not need to remember which session ID belonged to which task because the tile preserves that association for you. The app costs 99 dollars once and one key runs one computer at a time. This permanent license model fits well with a developer's workflow, where you want a reliable tool that does not require a recurring subscription or an account to manage your local coding agent sessions.
Checking cost and usage
After an update, it is a good habit to monitor the performance and cost of your sessions. You can use the /cost and /usage slash commands to see how much you have spent and how many tokens you are using. Sometimes a new version of the tool might change how it handles context or how it uses tools like Glob or Grep. By checking your usage early, you can ensure that the new version is operating within your expected budget. If you find that a session is becoming too large and expensive, you can use the /compact command to summarize the conversation and free up context space.
The /compact command is especially useful after an update if you want to start fresh with the new logic while keeping the essential history of your work. It creates a summary of the session so far, which the agent can then use as a reference. This reduces the number of tokens sent in each prompt and can make the agent faster and more efficient. If you ever feel like the session has become too cluttered, the /clear command is also available to start over in the same folder without losing your overall project settings or history. These tools give you full control over your environment and your spending.
Questions people ask
Will my custom slash commands be deleted after I run the update?
No, your custom slash commands stay safe in the .claude/commands folder within your project. The update only changes the main executable and does not touch your project specific files or subdirectories. You can continue using your custom commands immediately after the update finishes.
How do I know if the update actually worked?
You should run the "claude doctor" command once the update process is complete. This tool performs a series of internal checks to verify that the installation is healthy and that all dependencies are correctly configured. It will report any issues it finds so you can fix them before starting a new coding session.
Can I go back to a session I was working on before the update?
Yes, you can use the "claude --resume" command to see a list of your previous sessions. Pick the one you were working on to pick up exactly where you left off. The history of your conversations is stored in your user profile, so it persists even when the tool itself is updated.
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.