The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: align session commands with session manager
Affaan Mustafa8f87a5408ff2
diff --git a/commands/resume-session.md b/commands/resume-session.mdindex 9cba97af0..5f84cf610 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-<shortid>-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-<shortid>-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 Authenticationdiff --git a/commands/save-session.md b/commands/save-session.mdindex 0f3ceeac5..676d74cdd 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-<short-id>-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-<short-id>-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` (uFull 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-<short-id>-session.tmp`) for any new session file