Why `--continue` Misses Sessions
The `claude --continue` command is designed to resume your last coding session within a specific folder. However, it falters when the session is not the most recent one initiated in that directory, or if it was started from a different directory entirely. Claude Code organizes sessions by folder. It stores these sessions under ~/.claude/projects/. Each project within this directory is named after the full path from which the claude command was originally executed. Special characters like slashes and underscores in the path are converted into dashes in the folder name. The `--continue` flag, by design, only targets the absolute latest session associated with your current working directory. This selective approach means it can easily overlook or fail to find a session if other, newer sessions have been started in the same folder since, or if the intended session originated from a parent directory or a distinct project location.
Step 1: Locate Available Session Folders
The first step to recovering a lost session is to identify all the session folders Claude Code has created. These are stored in the ~/.claude/projects/ directory. To list these folders, open your terminal and run the following command:
ls ~/.claude/projects/
This command will display a list of subdirectories within ~/.claude/projects/. Each subdirectory name corresponds to a previously launched Claude Code session, with the directory path encoded using dashes. You need to carefully examine this list to find the folder that most closely matches the directory path where you were working or from which you initially launched Claude Code.
Step 2: Identify the Correct Session Folder
Once you have the list of session folders, the next challenge is to pinpoint the exact folder for your lost session. The naming convention, where directory paths are transformed into folder names, can be tricky. For instance, if you launched Claude from ~/projects/my-awesome-app, the corresponding folder in ~/.claude/projects/ might look something like projects-my-awesome-app or similar, depending on the exact path and how Claude handles encoding. Pay close attention to the structure and naming. If you initiated sessions from multiple locations or within nested directories, you might see several related folders. You may need to inspect the timestamps of these folders (using ls -lt ~/.claude/projects/) or their contents to determine which one corresponds to the session you wish to recover. Look for the folder that represents the project directory you were working in when the session was active.
Step 3: Manually Restore the Session
If claude --continue fails, you can manually restore a session by navigating to the root directory of your project and then executing the claude command with the specific session path. First, change your current directory to the root of your project. For example, if your project is located at ~/projects/my-awesome-app, you would run:
cd ~/projects/my-awesome-app
After navigating to your project's root directory, you need to tell Claude Code which session to load. This is done by specifying the path to the session folder relative to the ~/.claude/projects/ directory. The command would look something like this:
claude --session ~/.claude/projects/projects-my-awesome-app
Replace projects-my-awesome-app with the actual name of the session folder you identified in Step 2. This command explicitly directs Claude Code to load the session data from the specified folder, bypassing the automatic detection mechanism of `--continue`. This manual intervention ensures you can access your work even when the automated command fails.
Understanding the `--session` Flag
The `--session` flag is your direct interface to Claude Code's session management. Unlike `--continue`, which relies on heuristics to guess the correct session, `--session` requires an explicit path. This makes it a more robust option when the automated process breaks down. It’s akin to providing a direct file path to an application instead of asking it to find the most recently opened document. Knowing this flag is crucial for developers who encounter situations where their workflow is interrupted and the automatic resumption fails. It empowers users to take control and manually retrieve their work, preventing data loss and minimizing downtime.
Preventing Future Session Loss
To avoid future headaches with lost sessions, be mindful of how and where you initiate your Claude Code sessions. Always try to launch claude from the root directory of your project. If you frequently switch between projects or work in deeply nested directories, consider creating small wrapper scripts or aliases that always launch claude from the intended project root. For example, you could create a script named claude-my-app in your path that contains:
#!/bin/bash
cd ~/projects/my-awesome-app && claude --continue
This ensures that even if you are in a subdirectory, running claude-my-app will first change to the project root and then attempt to resume the session, making `--continue` more likely to succeed. Understanding the session folder structure and the `--session` flag provides a reliable fallback when the primary recovery method fails, ensuring your coding sessions are always recoverable.