Skip to content
Datfx Labs Claude Guide

Session Management

Every claude invocation starts a session. A session is a persistent context window: Claude remembers everything that happened in it — files you’ve discussed, decisions you’ve made, code you’ve written together. Sessions survive terminal restarts and computer reboots.

Managing sessions well is what separates developers who feel like they’re constantly re-explaining context from those who pick up exactly where they left off.

Session Basics

Each session has:

  • A unique ID (used for resuming)
  • A label (human-readable name you assign)
  • A model (can be changed mid-session)
  • A context window with current usage
  • Creation time and last-active time

Sessions are persistent by default. When you close a terminal, the session doesn’t disappear — it’s saved and resumable.

Naming Sessions

Terminal window
claude --label "feat-auth"
claude -w --label "auth-oauth-impl"

Labels are essential once you’re running more than one session. Without them, your session list looks like:

session_a3f9b2   running   (no label)
session_c7d4e1   paused    (no label)
session_8b2a3f   completed (no label)

With labels:

feat-auth-planning     running
feat-auth-oauth-impl   paused
feat-auth-tests        completed

The label shows up in /sessions, the Desktop sidebar, and notification messages. Make it describe the task, not the date.

Listing Sessions

Terminal window
claude sessions

Output:

ID              Label                  Model      Context    Status     Last Active
a3f9b2...       feat-auth-planning     opus       42%        running    now
c7d4e1...       auth-oauth-impl        sonnet     78%        paused     2h ago
8b2a3f...       dep-update-q1          haiku      12%        completed  1d ago

The Context column is important: at 78%, a session is getting close to the limit where you’ll want to compact before resuming.

Resuming Sessions

Terminal window
claude --resume a3f9b2
claude --resume latest          # shortcut for most recent session

When you resume, Claude has the full conversation history. You don’t need to re-explain what you were working on, what decisions were made, or what the current state of the code is. The context is intact.

This matters most after breaks. Coming back to a task after lunch, the next morning, or after a week away — resuming the session means the cognitive overhead of re-establishing context is near zero.

Note: If the code has changed significantly since the session was last active (other PRs merged, refactoring done by a teammate), the session’s context may be stale. Use /compact after resuming to let Claude re-read the current state of the relevant files.

Session Lifecycle

flowchart TD A([New task]) --> B[Start session\nwith label] B --> C[Work] C --> D{Context\nusage?} D -->|< 50%| C D -->|50-80%| E[/compact\nthen continue] E --> C D -->|> 80%| F{Is task\ncomplete?} F -->|Yes| G([End session]) F -->|No| H{Need different\napproach?} H -->|Yes| I[Fork session\n/branch] H -->|No| J[Compact +\ncontinue] J --> C C --> K{Break?} K -->|Short| L[Resume later\n--resume latest] L --> C K -->|Task done| G style A fill:#1e293b,color:#7dd3fc,stroke:#334155 style B fill:#1e293b,color:#7dd3fc,stroke:#334155 style C fill:#1e293b,color:#7dd3fc,stroke:#334155 style D fill:#1e293b,color:#fcd34d,stroke:#334155 style E fill:#1e293b,color:#7dd3fc,stroke:#334155 style F fill:#1e293b,color:#fcd34d,stroke:#334155 style G fill:#1e293b,color:#86efac,stroke:#334155 style H fill:#1e293b,color:#fcd34d,stroke:#334155 style I fill:#1e293b,color:#7dd3fc,stroke:#334155 style J fill:#1e293b,color:#7dd3fc,stroke:#334155 style K fill:#1e293b,color:#fcd34d,stroke:#334155 style L fill:#1e293b,color:#7dd3fc,stroke:#334155

When to Start New vs Resume vs Fork

Resume the same session when:

  • You’re continuing the same feature or task
  • You took a break but the context is still valid
  • The codebase hasn’t changed significantly while you were away

Start a new session when:

  • The task is completely different (new feature, unrelated bug)
  • The old context is more noise than signal
  • You’re switching from implementation to a separate code review

Fork the session when:

  • You want to try a different approach without abandoning your current one
  • You need to explore a risky change that might not pan out
  • You want a clean version to compare against

See Branch for the fork/branch pattern in depth.

Multi-Session Naming Convention

When running parallel sessions on related work, a consistent naming pattern makes coordination much easier:

Terminal window
# Feature work split across sessions
claude -w --label "auth-planning"
claude -w --label "auth-impl-login"
claude -w --label "auth-impl-oauth"
claude -w --label "auth-tests"
claude -w --label "auth-docs"

Pattern: {feature}-{phase} or {feature}-{component}. The feature prefix groups related sessions together in the session list.

For team environments, prefix with your name or initials:

Terminal window
claude -w --label "jl-auth-impl-login"
claude -w --label "jl-auth-impl-oauth"

Exporting Sessions

Terminal window
/export

Saves the full conversation to a markdown file. Useful for:

  • Sharing a session’s reasoning and decisions with a teammate
  • Archiving the design discussion that led to a particular implementation
  • Creating documentation from a session where you designed an API together
  • Code review — the reviewer can see not just what changed but why

The export includes all messages, code blocks, and tool outputs in readable markdown.

Context Decay

Sessions don’t stay useful forever. Two causes:

Context saturation: as the context window fills, older messages receive less weight. A session at 90% context is less effective than one at 40%.

Code divergence: if significant code changes happened outside the session (merged PRs, teammates’ commits), Claude’s mental model of the codebase no longer matches reality.

For long-dormant sessions, use /compact immediately after resuming:

Terminal window
claude --resume feat-auth-planning
/compact

/compact distills the conversation history to its essential decisions and context, freeing up context window space and giving Claude a fresh read of current file state.

See Context Management for the full compaction strategy.

Desktop App Session Management

The Desktop app provides a visual session browser in the left sidebar:

  • All sessions listed with label, status indicator, and last-active time
  • Click any session to switch to it immediately
  • Background sessions show a spinner while active
  • Completed sessions show a checkmark
  • Blocked sessions show a warning icon

The Desktop app is the recommended way to manage more than 3 parallel sessions — the visual overview makes it much easier to track state than juggling terminal windows.

Remote Sessions and Teleport

Sessions started on one machine can be accessed from another via Teleport. The session state (context, conversation, in-progress work) is synchronized — you can start a session on your desktop, step away, and resume on your laptop.

See Teleport for the full remote session workflow.

Session and Context Management Together

Session management (which session to use, when to resume or fork) and context management (compacting, clearing, selective loading) are closely related but distinct:

  • Session management: which conversation thread to work in
  • Context management: what’s in that thread’s active context window

The most effective workflow combines both: label sessions clearly so you always resume the right one, and compact proactively so the context window stays useful.

See Context Management for the context half of this picture.

  • Branch — forking a session to try an alternative approach
  • Teleport — remote session access across devices
  • Context Management — keeping the context window effective
  • Git Worktrees — isolated branch state for parallel sessions