Claude Code Session Management: Resume, Session Files, and Cross-Device Workflows

Sessions Are Not Just Terminal History

When you run claude and start working, a session object is created that tracks what you have done, what files have been modified, what the current state of the codebase is, and what you were trying to accomplish. This is not just a scrollback buffer — it is structured state that Claude Code uses to reason about continuity.

That state persists for the lifetime of the session. If your terminal crashes, the session is still there. If you get disconnected mid-task, you can reconnect to the same session and continue. If you want to switch machines mid-work, the session file gives you a way to pick up where you left off.

Understanding how sessions work lets you use them deliberately rather than just stumbling into them.

Resuming a Previous Session

Run claude --resume and Claude Code will list your recent sessions with timestamps and brief descriptions of what each involved. Pick the one you want and it restores the context — your project state, the conversation history, what had been attempted.

claude --resume
# Shows:
# [1] Refactor auth module — 2 hours ago
# [2] Debug checkout flow — yesterday
# [3] Write tests for payment processor — 3 days ago

Pick one and you are back in the same context, able to continue from where the session ended. This is useful when you are working on something that spans multiple days or when you got interrupted mid-task and need to get back up to speed.

The session history is stored locally. How long sessions are kept depends on your configuration — by default, recent sessions are available, older ones eventually fall off. You can increase the history limit if you want to keep more sessions accessible.

Session Files and Where They Live

Session state is stored in your Claude Code config directory. On macOS and Linux, that is ~/.config/claude/. On Windows, it is %APPDATA%/claude/. Inside that directory, sessions are stored as JSON files with structured data about project context, conversation history, and tool use records.

You can back up session files manually if you want to preserve a session beyond its normal retention period. Copy the file to somewhere safe, and later you can restore it by placing it back in the sessions directory and resuming.

Do not edit session files directly — they are structured for Claude Code's internal use and manual edits can corrupt them. Treat them as opaque artifacts that you move around but do not modify.

Cross-Device Session Sharing

Claude Code runs locally, which means sessions live on the machine where you ran them. If you work on a desktop and a laptop, you might want to continue a session on the second machine rather than starting fresh.

The mechanism is manual but straightforward: on the machine where the session exists, find the session file, copy it to the other machine (via USB, cloud drive, rsync, whatever), place it in the sessions directory, and resume. The session file contains enough context for Claude Code to reconstruct where you were.

The catch: the session file assumes the project files exist on the target machine in the same locations. If you were working in ~/projects/my-app and that directory does not exist on the second machine, the session will restore but Claude Code will not be able to access the files. For cross-device sessions to work, you need the project directory present with the same relative path.

For teams working on the same codebase from multiple machines, this usually is not a problem — you have git pulling the same files to both machines. For personal projects where files are on one machine and not synced, the session file alone will not be enough.

Session Configuration Options

You can control session behavior through claude_settings.json:

{
  "resumeSessions": true,
  "sessionHistoryLimit": 50,
  "confirmDeletes": true
}

resumeSessions defaults to true — set it false if you never want Claude Code to offer resuming previous sessions. sessionHistoryLimit controls how many past sessions are kept in the history. Raise it to keep more sessions available. confirmDeletes makes Claude Code ask before deleting files — useful if you want to review dangerous operations before they execute.

When Sessions Go Wrong

Sometimes a session gets into a state where continuing is harder than starting fresh. Claude Code might have lost track of what it was doing, or the context might have degraded to the point where resuming is not productive. In that case, end the session cleanly:

/exit

This closes the session properly and gives Claude Code a chance to write final state. From there, start a new session. You can describe what you were working on and pick up from a point a little before where things went wrong, which is often faster than trying to fix a degraded session.

If a session crashes unexpectedly, the state is usually preserved. Next time you run claude --resume, the interrupted session appears and you can continue from where it left off. The only case where state is lost is if the session file itself was corrupted — which is rare but possible if the machine lost power mid-write.

The Practical Session Workflow

Most of the time, you start a session, work on something, and finish. When you are done, you exit and the session gets stored. Later, you might resume it if you want to continue that work or review what was done.

The cross-device case is less common but valuable when you need it. If you are traveling and only have your laptop, but the work was on your desktop, you copy the session file over, sync the project files, and pick up where you left off. It is not seamless, but it works.

The session system is not trying to be a full collaboration tool — it is about continuity on the same machine and manual handoff between machines. For real-time collaboration across devices, that is a different layer on top that teams have built, but it is not built into Claude Code itself.