feat: add resume and save session commands for session management#367
Open
avesh-h wants to merge 6 commits intoaffaan-m:mainfrom
Open
feat: add resume and save session commands for session management#367avesh-h wants to merge 6 commits intoaffaan-m:mainfrom
avesh-h wants to merge 6 commits intoaffaan-m:mainfrom
Conversation
Introduced two new commands: `/resume-session` and `/save-session`. The `/resume-session` command allows users to load the most recent session file or a specific session file, providing a structured briefing of the session's context. The `/save-session` command captures the current session state, saving it to a dated file for future reference. Both commands enhance user experience by enabling seamless session continuity and context preservation.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds two new documentation pages, Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="commands/resume-session.md">
<violation number="1" location="commands/resume-session.md:40">
P2: Step 1's date-handling instruction contradicts the edge-case rule about multiple same-day sessions. When a date argument is provided, the process says to look for `.claude/sessions/YYYY-MM-DD.md` specifically, but the edge-cases section says to pick the highest-numbered variant (e.g. `YYYY-MM-DD-2.md`). The agent will follow Step 1 and miss the latest session file.</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Add one-off context when rerunning by tagging
@cubic-dev-aiwith guidance or docs links (includingllms.txt) - Ask questions if you need clarification on any suggestion
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
commands/resume-session.md (1)
98-98: Consider alternative to "very old".The phrase "very old date" could be more specific, e.g., "Session file is from more than N days ago" where N is a concrete threshold.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@commands/resume-session.md` at line 98, Update the message "Session file is from a very old date:" to use a concrete threshold, e.g., "Session file is from more than N days ago" (or substitute the actual configured threshold variable) so readers know the cutoff; locate the string "Session file is from a very old date:" in the resume-session content and replace it with wording that includes the numeric threshold (or references the config/constant) and, if applicable, show the exact N value used by the application.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@commands/resume-session.md`:
- Around line 92-93: The documentation section titled "Multiple sessions for the
same date" should be updated to match the actual collision strategy implemented
in session-manager.js: replace the numeric-suffix example and wording with the
short-id hash scheme used by the code (e.g., files named like
2024-01-15-<shortid>-session.tmp) and state that the loader picks the session
file generated with a short-id (i.e., the most recent unique short-id instance)
instead of incrementing numeric suffixes; reference the "Multiple sessions for
the same date" header and session-manager.js collision handling when making this
change.
- Around line 1-23: Update the resume-session documentation to match the actual
session-manager implementation: replace every occurrence of ".claude/sessions/"
with "~/.claude/sessions/", change examples and descriptions to use the ".tmp"
extension instead of ".md", and explicitly show the full filename pattern that
ends with "-session.tmp" (e.g., "2024-01-15-abc123-session.tmp" or
"2024-01-15-session.tmp") in the description, usage examples, behavior notes,
and output examples within the Resume Session Command document so all examples
and explanatory lines reference the correct directory, extension, and naming
pattern.
In `@commands/save-session.md`:
- Around line 1-31: The docs currently instruct creating .claude/sessions and
naming files as YYYY-MM-DD.md, but the implementation in
scripts/lib/session-manager.js uses ~/.claude/sessions and filenames like
YYYY-MM-DD-<short-id>-session.tmp; update the documentation (including the mkdir
example and all references to session filenames) to use the canonical path
~/.claude/sessions and the actual naming scheme
YYYY-MM-DD-<short-id>-session.tmp so examples and file operations match
session-manager.js and any functions that create/read session files.
- Around line 35-37: The documentation and implementation disagree on collision
handling: docs say numeric suffixes (YYYY-MM-DD-2.md) but session-manager.js
uses short-id hashes (e.g., a1b2c3d4). Update session-manager.js to use numeric
suffixing and ensure resume logic expects the same: change the filename
generation in the function that creates session files (e.g.,
generateSessionFilename or createSessionFile) to check for existing
YYYY-MM-DD.md and iterate N to produce YYYY-MM-DD-N.md, update saveSession to
write with that name, and update resumeSession or the function that parses
session filenames to look for numeric-suffixed files rather than short-id hashes
so all commands use the same filename scheme.
---
Nitpick comments:
In `@commands/resume-session.md`:
- Line 98: Update the message "Session file is from a very old date:" to use a
concrete threshold, e.g., "Session file is from more than N days ago" (or
substitute the actual configured threshold variable) so readers know the cutoff;
locate the string "Session file is from a very old date:" in the resume-session
content and replace it with wording that includes the numeric threshold (or
references the config/constant) and, if applicable, show the exact N value used
by the application.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1c7fc426-e31b-4a0b-9a02-5e86feb36164
📒 Files selected for processing (2)
commands/resume-session.mdcommands/save-session.md
Updated the documentation for the `/resume-session` and `/save-session` commands to reflect the correct file paths, changing references from `.claude/sessions/` to `~/.claude/sessions/`. This ensures clarity on the global directory used for session management and maintains consistency across commands.
affaan-m
reviewed
Mar 9, 2026
Owner
affaan-m
left a comment
affaan-m
left a comment
There was a problem hiding this comment.
Automated review: waiting for checks to complete.
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="commands/save-session.md">
<violation number="1" location="commands/save-session.md:35">
P2: Using `.tmp` extension for persistent session files risks accidental deletion. These files contain structured markdown meant to survive across sessions and be loaded by `/resume-session`. The `.tmp` convention signals "temporary/disposable," which contradicts the file's purpose. Consider using `.md` — it matches the content format and signals that the file should be kept.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@commands/save-session.md`:
- Around line 35-37: Update the docs to specify the exact short-id format
enforced by SESSION_FILENAME_REGEX in session-manager.js: state that the
short-id must contain only lowercase letters a-z, digits 0-9 and hyphens, with a
minimum length of 8 characters (no underscores, no uppercase), and give a couple
of valid/invalid examples (e.g., valid: 2024-01-15-abc123de-session.tmp;
invalid: ABC123de, short, test_id1) so users cannot create filenames that the
session manager will reject.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 12aeacff-4dc7-413a-9a29-d3268844bef1
📒 Files selected for processing (2)
commands/resume-session.mdcommands/save-session.md
🚧 Files skipped from review as they are similar to previous changes (1)
- commands/resume-session.md
Updated the documentation for the `/save-session` command to include detailed rules for generating the session short-id, including allowed characters, minimum length, and examples of valid and invalid formats. This improves clarity and helps users adhere to the required naming conventions.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@commands/save-session.md`:
- Around line 266-272: The docs claim session files are "meant to be read by
Claude at the start of the next session via /resume-session" but the parser
parseSessionMetadata in session-manager.js does not recognize the documented
sections (e.g., "What Did NOT Work", "What Worked", "Decisions", "Blockers"), so
structured metadata cannot be extracted; update either the document or the
parser: modify parseSessionMetadata to support the section headers and format
described in commands/save-session.md (recognize and parse the "What Did NOT
Work", "What Worked", "Decisions", "Blockers", and in-progress markers) so
/resume-session can extract structured metadata, or alternatively change the doc
to state that only raw content is read and list the actual parsed fields
returned by parseSessionMetadata.
- Around line 66-178: The session file headings in save-session.md (multiple
"##" sections like "What We Are Building", "What WORKED", etc.) don't match the
headings parseSessionMetadata in scripts/lib/session-manager.js expects (###
Completed, ### In Progress, ### Notes for Next Session, ### Context to Load), so
metadata is dropped on resume; fix by either updating parseSessionMetadata to
recognize and extract the documented "##" headings (map each documented section
name to the corresponding metadata field the loader uses and add parsing logic
in parseSessionMetadata/ session-manager.js and ensure resume-session invokes
it), or update save-session.md to use the exact "###" section titles and names
parseSessionMetadata expects (rename headings to "### Completed", "### In
Progress", "### Notes for Next Session", "### Context to Load") so existing
parser continues to work. Ensure references to parseSessionMetadata and
resume-session remain consistent after the change.
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.
There was a problem hiding this comment.
2 issues found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="commands/resume-session.md">
<violation number="1" location="commands/resume-session.md:59">
P2: The briefing template hardcodes `.claude/sessions/` as the path prefix, but the session may have been loaded from the global `~/.claude/sessions/` location. This will produce a misleading `SESSION LOADED:` line when the fallback path is used. Use the actual resolved path instead, and update the Example Output section to match.</violation>
</file>
<file name="commands/save-session.md">
<violation number="1" location="commands/save-session.md:29">
P2: The frontmatter `description` still references `~/.claude/sessions/` while the body now defaults to `.claude/sessions/`. Update the description to match the new project-level default so tooling and command listings show the correct path.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@commands/resume-session.md`:
- Around line 56-60: Replace the hardcoded session path in the briefing template
with the actual loaded file path variable so the acknowledgement reflects the
real source; update the template in commands/resume-session.md (the "SESSION
LOADED: .claude/sessions/..." header) to emit the runtime path (e.g., use the
loadedSessionPath / sessionFilePath variable or equivalent used by the loader)
instead of the literal ".claude/sessions/..." string and keep the rest of the
header formatting unchanged.
In `@commands/save-session.md`:
- Around line 2-3: The docs for the /save-session command are inconsistent about
the default save location (lines mention both ~/.claude/sessions/ and
project-local .claude/sessions/); update commands/save-session.md to unify the
default behavior (choose either project-local `.claude/sessions/` as default
with a global override, or global `~/.claude/sessions/`) and make every
occurrence (the top description, examples at lines ~29-35, ~39-40, ~58-63, and
the confirmation text at ~275-277) reflect that single default; also change the
hardcoded confirmation string ("Session saved to .claude/sessions/...") to
display the actual resolved session file path dynamically (e.g., "Session saved
to [actual session file path]") so the final message always matches where the
file was written.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4b7f79a5-a56b-46af-8390-df1f2f148c3b
📒 Files selected for processing (2)
commands/resume-session.mdcommands/save-session.md
…mmands Revised the documentation for both the and commands to clarify that session files are saved and loaded from the project-level directory, rather than the global directory. This change enhances user understanding of session management and ensures consistency in file path references.
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
commands/save-session.md (1)
58-67:⚠️ Potential issue | 🟡 MinorMake the confirmation message path dynamic.
The confirmation message on line 61 is hardcoded to
.claude/sessions/, but Step 2 (line 35) allows saving to~/.claude/sessions/when the user explicitly requests global storage. When global storage is used, the confirmation will show the wrong path, confusing users about where their file was saved.📝 Proposed fix
After writing, display the full contents and ask:-Session saved to .claude/sessions/YYYY-MM-DD--session.tmp
+Session saved to [actual path: .claude/sessions/ or ~/.claude/sessions/]/YYYY-MM-DD--session.tmpDoes this look accurate? Anything to correct or add before we close?
Or more simply:
After writing, display the full contents and ask:-Session saved to .claude/sessions/YYYY-MM-DD--session.tmp
+Session saved toDoes this look accurate? Anything to correct or add before we close?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@commands/save-session.md` around lines 58 - 67, The confirmation message currently hardcodes "Session saved to .claude/sessions/YYYY-MM-DD-<short-id>-session.tmp"; change it to display the actual filepath returned/used when saving (e.g., use the saved session path variable instead of the hardcoded string), ensuring "~" is expanded to the full path when global storage is selected so the user sees the true location; keep the existing confirmation prompt and wait-for-confirmation flow unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@commands/save-session.md`:
- Around line 58-67: The confirmation message currently hardcodes "Session saved
to .claude/sessions/YYYY-MM-DD-<short-id>-session.tmp"; change it to display the
actual filepath returned/used when saving (e.g., use the saved session path
variable instead of the hardcoded string), ensuring "~" is expanded to the full
path when global storage is selected so the user sees the true location; keep
the existing confirmation prompt and wait-for-confirmation flow unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 153b2de0-5a5e-4f0c-af1b-e263e63a720e
📒 Files selected for processing (2)
commands/resume-session.mdcommands/save-session.md
🚧 Files skipped from review as they are similar to previous changes (1)
- commands/resume-session.md
Revised the documentation for the `/save-session` command to reflect the actual resolved path to the session file, enhancing clarity for users regarding where their session data is stored. This change aligns with previous updates to session file management.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduced two new commands:
/resume-sessionand/save-session. The/resume-sessioncommand allows users to load the most recent session file or a specific session file, providing a structured briefing of the session's context. The/save-sessioncommand captures the current session state, saving it to a dated file for future reference. Both commands enhance user experience by enabling seamless session continuity and context preservation.Description
Type of Change
fix:Bug fixfeat:New featurerefactor:Code refactoringdocs:Documentationtest:Testschore:Maintenance/toolingci:CI/CD changesChecklist
node tests/run-all.js)Summary by cubic
Add
/save-sessionand/resume-sessioncommands to capture and reload session context with a fixed, readable briefing. Sessions save to project.claude/sessions/by default (fallback to~/.claude/sessions/), and save confirmation now shows the actual resolved path.New Features
/save-session: collects session context; saves to.claude/sessions/YYYY-MM-DD-<short-id>-session.tmp(a–z, 0–9,-, min 8 chars); displays full file and resolved path for confirmation./resume-session: loads latest or a specific date/path (project first, then~/.claude/sessions/); supportsYYYY-MM-DD-session.tmpandYYYY-MM-DD-<shortid>-session.tmp; returns a fixed-format briefing and waits for direction; handles stale, missing, or malformed files.Bug Fixes
Written for commit 5199c0c. Summary will update on new commits.
Summary by CodeRabbit