Try free

Last updated 13 October 2026

Move Claude Code sessions between computers

Your session state stays on your local machine

Transitioning between different development environments is a common challenge when you rely on an interactive agent like Claude Code. You might start a deep architectural refactoring on your office workstation and find that you need to continue the task on your laptop during your commute. Because the tool stores its history and project context on your local disk rather than in a centralized cloud, your progress does not follow your login automatically. If you simply run the command on a new machine, you will find a blank slate, which forces you to spend time re-explaining your goals and waiting for the agent to re-scan your repository.

The state of an active session includes the history of your messages, the files the agent has already examined, and the specific memory it has built up about your project structure. Moving this data requires a deliberate transfer of specific files from your home directory. By understanding where the tool stores its records, you can migrate your work and pick up exactly where you left off. This process ensures that you do not waste your token budget on redundant context gathering when you switch devices.

Use the repository to carry project instructions

The most straightforward part of moving your environment is the CLAUDE.md file. This file sits in your repository root and acts as the primary manual for the agent. It contains your build commands, test patterns, and style preferences. Because this file is part of your project tree, it should be tracked by your version control system. When you pull your latest changes on a new machine, the agent will immediately have access to these instructions. This provides a baseline level of consistency across all computers where you work on that specific codebase.

If your project has a complex structure, you might also have secondary CLAUDE.md files in subdirectories. These provide more specific rules for different parts of the tree. Ensuring these are committed to git is the best way to maintain a shared understanding between you and the agent. However, while these files guide how the agent behaves, they do not store the history of what you just discussed in your last session. For that, you must look outside the repository and into your user configuration folders.

Sync your global preferences for a consistent experience

Global settings govern how the tool interacts with your system across all projects. These are stored in a hidden directory in your home path, specifically in a file called settings.json within the .claude folder. This file defines your default permission modes and which tools are allowed to run without constant manual approval. For example, if you have configured the agent to use the Bash or Edit tools under the acceptEdits mode on one machine, you should copy this file to your new machine to avoid being prompted for every single change again.

If you have defined custom slash commands as markdown files in the .claude/commands directory of your home folder, these must also be moved. These commands are useful for automating repetitive tasks that are not specific to one project. You can copy the entire .claude directory from your home folder to the new machine to ensure that your global configuration is identical. This prevents friction when you try to use a familiar command and find that the agent no longer recognizes it on the new hardware.

Distinguish between shared and local project settings

Inside your project folder, the .claude directory can contain two different configuration files. The settings.json file is usually meant to be shared with your team and kept in version control. It might define the specific model the agent should use or the default permission levels for that repository. When you move to a new computer, this file arrives with your code. However, you must also look for settings.local.json, which is intended for your own overrides that you do not want to commit to the repository.

The local settings file often contains paths or configurations that are unique to your current machine. If you have customized how the agent interacts with your local environment, such as specific IDE integration settings, you will need to copy this file manually. If you ignore this file, you might find that the agent tries to use tools or paths that were valid on your desktop but do not exist on your laptop. Manually syncing these files ensures that the project-specific behavior remains predictable regardless of the physical hardware you are using.

Migrate the history database to maintain conversation context

The actual conversation history is kept in a database inside a subfolder of your hidden home directory. This is the data that the claude --resume command looks for when it offers you a list of previous interactions. To move your active sessions, you must copy the contents of the folder where the tool saves these logs. Since this is not a standard file that you edit, you should use a reliable transfer method like rsync or a secure cloud drive to mirror the entire folder structure between your machines.

When you arrive at the new machine, ensure the tool is installed by running the claude doctor command. This check confirms that the directory structure is ready to receive your migrated data. Once you place the history files in the correct path, you can use the /resume command inside a session or the --resume flag from your terminal to see your old conversations. This allows you to jump back into a complex task without having to summarize your previous progress to the agent.

Verify your new installation before resuming work

After moving your files, it is vital to check that everything is functioning as expected. Start by running claude update to make sure you are using the latest version of the tool on the new machine. Differences in versions can sometimes cause issues with how history files are read. Once the tool is updated, initiate a session and use the /status command. This will show you the current state of the agent and confirm if it recognizes the context of the project correctly.

If you encounter errors during the resume process, check the file permissions in your home directory. Sometimes files moved from a different operating system or user account might have restricted access, preventing the tool from reading the session database. You can also use the /doctor command within an active session to identify any problems with the environment. If the history is too large or cluttered after the move, you might use /compact to summarize the session and free up space in the context window.

Manage external tools and server configurations

If your workflow involves Model Context Protocol servers, you have additional files to consider. These servers are configured in a file called .mcp.json, which determines how the agent connects to external data sources or tools. If this file points to local scripts or binaries, those files must exist at the same paths on your new computer. If the paths differ, the agent will fail to start the MCP servers, and you will lose access to the tools you need for your task.

You can manage these servers using the claude mcp command to see which ones are active. If you have moved to a machine with a different operating system, you may need to adjust the command strings in your MCP configuration to match the new environment. Ensuring that your MCP servers are correctly mirrored is just as important as moving your conversation history, as many advanced tasks depend on these external capabilities to read data or execute specialized code.

Keep your workspace organized across multiple devices

Maintaining a consistent developer experience across multiple machines requires more than just moving files. It requires a way to visualize and manage all your active tasks. If you find yourself managing many complex sessions, adhdTerminal offers a way to keep your work organized. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It allows you to run multiple Claude Code sessions side by side as tiles on a wall, where each tile shows whether the agent is working, waiting, or idle.

When you move between computers, adhdTerminal makes it easier to track your progress because your tiles reopen in the same place after a restart and resume the same session. You can even use a free iPhone app to mirror your wall over an end to end encrypted link, allowing you to answer a prompt or send a task while you are away from your main machine. It costs 99 dollars once, and one key can be moved between your computers, making it a useful tool for developers who need to maintain a high level of situational awareness while migrating their sessions.

Questions people ask

Will my cost and usage history move between computers?

Yes, if you copy the entire hidden folder from your home directory, your usage statistics will be preserved. You can use the /cost and /usage commands on the new machine to see the total spend associated with those sessions. This data is stored locally in the same database that holds your conversation history.

What happens if the project path is different on the new machine?

The tool identifies sessions by the folder they were started in. If you move your project to a different path on the new computer, the claude --resume command might not automatically link your history to that folder. You may need to manually point the tool to the correct session or ensure your project paths remain identical across devices.

Do I need to log in again on the new computer?

Yes, your login session is usually tied to the specific machine and browser. Even if you move your configuration files, you should run /login on the new machine to ensure you have a valid authentication token. This ensures that the agent can communicate with the backend services to process your prompts.

Read next

More on when it goes wrong·All posts