From 8f87a5408ff2e12c06d54621a443cc42ff14ad6e Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Tue, 10 Mar 2026 20:20:50 -0700 Subject: [PATCH] docs: align session commands with session manager --- commands/resume-session.md | 27 +++++++++++++-------------- commands/save-session.md | 16 +++++++--------- 2 files changed, 20 insertions(+), 23 deletions(-) diff --git a/commands/resume-session.md b/commands/resume-session.md index 9cba97af..5f84cf61 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/ in the current project (or ~/.claude/sessions/ globally) and resume work with full context from where the last session ended. +description: Load the most recent session file from ~/.claude/sessions/ and resume work with full context from where the last session ended. --- # Resume Session Command @@ -17,10 +17,10 @@ This command is the counterpart to `/save-session`. ## Usage ``` -/resume-session # loads most recent file in .claude/sessions/ (project level) +/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 ~/.claude/sessions/2024-01-15-abc123-session.tmp # loads from global location +/resume-session ~/.claude/sessions/2024-01-15-session.tmp # loads a specific legacy-format file +/resume-session ~/.claude/sessions/2024-01-15-abc123de-session.tmp # loads a current short-id session file ``` ## Process @@ -29,20 +29,19 @@ This command is the counterpart to `/save-session`. If no argument provided: -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: +1. Check `~/.claude/sessions/` +2. Pick the most recently modified `*-session.tmp` file +3. If the folder does not exist or has no matching files, tell the user: ``` - No session files found in .claude/sessions/ or ~/.claude/sessions/ + No session files found in ~/.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`), 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) +- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/sessions/` for files matching + `YYYY-MM-DD-session.tmp` (legacy format) or `YYYY-MM-DD--session.tmp` (current format) and load the most recently modified variant for that date - If it looks like a file path, read that file directly - If not found, report clearly and stop @@ -95,8 +94,8 @@ If no next step is defined — ask the user where to start, and optionally sugge ## Edge Cases -**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123-session.tmp`): -Load the most recently modified file for that date. +**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`): +Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format. **Session file references files that no longer exist:** Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk." @@ -115,7 +114,7 @@ Report: "Session file found but appears empty or unreadable. You may need to cre ## Example Output ``` -SESSION LOADED: .claude/sessions/2024-01-15-abc123-session.tmp +SESSION LOADED: /Users/you/.claude/sessions/2024-01-15-abc123de-session.tmp ════════════════════════════════════════════════ PROJECT: my-app — JWT Authentication diff --git a/commands/save-session.md b/commands/save-session.md index 0f3ceeac..676d74cd 100644 --- a/commands/save-session.md +++ b/commands/save-session.md @@ -1,5 +1,5 @@ --- -description: Save current session state to a dated file in .claude/sessions/ (project level by default) so work can be resumed in a future session with full context. +description: Save current session state to a dated file in ~/.claude/sessions/ so work can be resumed in a future session with full context. --- # Save Session Command @@ -26,17 +26,15 @@ 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: +Create the canonical sessions folder in the user's Claude home directory: ```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` 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`: +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`: - Allowed characters: lowercase `a-z`, digits `0-9`, hyphens `-` - Minimum length: 8 characters @@ -47,7 +45,7 @@ Invalid examples: `ABC123de` (uppercase), `short` (under 8 chars), `test_id1` (u Full valid filename example: `2024-01-15-abc123de-session.tmp` -Each session always gets a unique short-id, so multiple sessions on the same day never collide. +The legacy filename `YYYY-MM-DD-session.tmp` is still valid, but new session files should prefer the short-id form to avoid same-day collisions. ### Step 4: Populate the file with all sections below @@ -273,5 +271,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` -- 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 +- Use the canonical global session store: `~/.claude/sessions/` +- Prefer the short-id filename form (`YYYY-MM-DD--session.tmp`) for any new session file