From 81022fdcfe9b234decb0020e838a63e6d5e369a4 Mon Sep 17 00:00:00 2001 From: avesh-h Date: Mon, 9 Mar 2026 21:27:32 +0530 Subject: [PATCH] docs: clarify session file paths and usage in resume-session command Updated the documentation for the `/resume-session` command to specify that session files are loaded from the project-level `.claude/sessions/` directory first, with a fallback to the global `~/.claude/sessions/` directory. Enhanced usage examples and clarified the process for locating session files, improving user understanding of session management. --- commands/resume-session.md | 22 ++++++++++++---------- commands/save-session.md | 13 +++++++++---- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/commands/resume-session.md b/commands/resume-session.md index 5ed86a77..3a08831a 100644 --- a/commands/resume-session.md +++ b/commands/resume-session.md @@ -1,5 +1,5 @@ --- -description: Load the most recent session file from ~/.claude/sessions/ and resume work with full context from where the last session ended. +description: Load the most recent session file from .claude/sessions/ in the current project (or ~/.claude/sessions/ globally) and resume work with full context from where the last session ended. --- # Resume Session Command @@ -17,9 +17,10 @@ This command is the counterpart to `/save-session`. ## Usage ``` -/resume-session # loads most recent file in ~/.claude/sessions/ -/resume-session 2024-01-15 # loads most recent session for that date -/resume-session ~/.claude/sessions/2024-01-15-abc123-session.tmp # loads specific file path +/resume-session # loads most recent file in .claude/sessions/ (project level) +/resume-session 2024-01-15 # loads most recent session for that date +/resume-session .claude/sessions/2024-01-15-abc123-session.tmp # loads specific file path +/resume-session ~/.claude/sessions/2024-01-15-abc123-session.tmp # loads from global location ``` ## Process @@ -28,18 +29,19 @@ This command is the counterpart to `/save-session`. If no argument provided: -1. List all `.tmp` files in `~/.claude/sessions/` -2. Pick the most recently modified file -3. If the folder doesn't exist or is empty, tell the user: +1. First check `.claude/sessions/` in the current project directory +2. If not found there, fall back to `~/.claude/sessions/` +3. Pick the most recently modified `.tmp` file from whichever location has files +4. If neither folder exists or both are empty, tell the user: ``` - No session files found in ~/.claude/sessions/ + No session files found in .claude/sessions/ or ~/.claude/sessions/ Run /save-session at the end of a session to create one. ``` Then stop. If an argument is provided: -- If it looks like a date (`YYYY-MM-DD`), find all files in `~/.claude/sessions/` matching +- If it looks like a date (`YYYY-MM-DD`), search `.claude/sessions/` first then `~/.claude/sessions/` for files matching `YYYY-MM-DD-session.tmp` (old format) or `YYYY-MM-DD--session.tmp` (new format) and load the most recently modified variant for that date - If it looks like a file path, read that file directly @@ -54,7 +56,7 @@ Read the complete file. Do not summarize yet. Respond with a structured briefing in this exact format: ``` -SESSION LOADED: ~/.claude/sessions/YYYY-MM-DD--session.tmp +SESSION LOADED: .claude/sessions/YYYY-MM-DD--session.tmp ════════════════════════════════════════════════ PROJECT: [project name / topic from file] diff --git a/commands/save-session.md b/commands/save-session.md index 348fd2e1..7c03d19c 100644 --- a/commands/save-session.md +++ b/commands/save-session.md @@ -26,13 +26,17 @@ Before writing the file, collect: ### Step 2: Create the sessions folder if it doesn't exist +Create the folder at the **project level** by default: + ```bash -mkdir -p ~/.claude/sessions +mkdir -p .claude/sessions ``` +If the user explicitly asks for global storage, use `~/.claude/sessions` instead. + ### Step 3: Write the session file -Create `~/.claude/sessions/YYYY-MM-DD--session.tmp` using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`: +Create `.claude/sessions/YYYY-MM-DD--session.tmp` in the current project directory, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`: - Allowed characters: lowercase `a-z`, digits `0-9`, hyphens `-` - Minimum length: 8 characters @@ -54,7 +58,7 @@ Write every section honestly. Do not skip sections — write "Nothing yet" or "N After writing, display the full contents and ask: ``` -Session saved to ~/.claude/sessions/YYYY-MM-DD--session.tmp +Session saved to .claude/sessions/YYYY-MM-DD--session.tmp Does this look accurate? Anything to correct or add before we close? ``` @@ -269,4 +273,5 @@ Then test with Postman — the response should include a `Set-Cookie` header. - The "What Did NOT Work" section is the most critical — future sessions will blindly retry failed approaches without it - If the user asks to save mid-session (not just at the end), save what's known so far and mark in-progress items clearly - The file is meant to be read by Claude at the start of the next session via `/resume-session` -- Keep this file in `~/.claude/sessions/` — this is a global directory shared across all projects, so session logs are not committed to any repo by default +- Save to `.claude/sessions/` inside the current project by default — this keeps session logs co-located with the project they belong to +- Use `~/.claude/sessions/` only if the user explicitly requests global storage or there is no active project directory