bobmatnyc/claude-mpm/mpm-session-resume

/mpm-session-resume

Load and display context from a paused session, with optional browsing and selection when multiple sessions exist.

What This Does

When invoked, this skill:

1. Scans the project-local session store at .claude-mpm/sessions/ for paused sessions
2. Loads the most recent session (by file modification time) or a specific

session selected with --select

1. Validates that the session's project_path matches the current project — sessions from other projects are skipped
2. Calculates time elapsed since pause and git changes since pause
3. Displays a formatted resume prompt with summary, accomplishments, and next steps
4. Returns the session data so the PM can continue work with full context

Note: Resume always validates that the session belongs to the current project.

You will never accidentally resume a session from a different project.

Usage

/mpm-session-resume                    # resume most recent session (existing behaviour)
/mpm-session-resume                    # with no args: also lists sessions when >1 exists
/mpm-session-resume --select 2         # resume the 2nd most-recent session (1-based index)
/mpm-session-resume --select 20240101  # resume by partial session ID match
/mpm-session-resume <session-id>       # resume by exact session ID (backward-compatible)

What it shows (listing mode — no args, multiple sessions):

• Numbered list of sessions, most-recent first
• Session ID (timestamp portion), time elapsed, project name, topic/summary

What it shows (resume mode):

• Session summary and time elapsed since pause
• Completed work and current tasks
• Git context and recent commits (new commits since pause)
• Pending TaskList items (from Claude Code TaskCreate/TaskList)
• Next recommended actions

Implementation

Run the console script directly — no interpreter resolution needed:

# Resume most recent session (lists if multiple exist)
claude-mpm session resume
 
# Resume the 2nd most recent session
claude-mpm session resume --select 2
 
# Resume by partial session ID (date prefix)
claude-mpm session resume --select 20240101
 
# Resume by exact session ID
claude-mpm session resume session-20240101-143022
 
# Resume from a specific project directory
claude-mpm session resume --project-path /path/to/project

Permission note (Bug #735): Do not probe for sessions with

ls .claude-mpm/sessions/ 2>/dev/null — that swallows stderr, so a

permission-denied read looks identical to "no sessions" and resume wrongly

reports nothing to resume. The claude-mpm session resume command handles

this correctly via check_session_dir_access().

If claude-mpm session resume fails

If the command exits non-zero, capture the full error and show it verbatim — do not summarise with a generic "not importable" message:

claude-mpm session resume 2>&1
rc=$?
if [ "$rc" -ne 0 ]; then
    echo ""
    echo "ERROR: claude-mpm session resume failed (exit $rc)."
    echo "Full error shown above."
    echo ""
    echo "Diagnostic steps:"
    echo "  1. Verify claude-mpm is on PATH:  command -v claude-mpm"
    echo "  2. Check the actual import error:  python3 -c 'import claude_mpm' 2>&1"
    echo "  3. If a transitive dep fails (e.g. shadowed stdlib module), check"
    echo "     sys.path[0] is not /tmp:  python3 -c 'import sys; print(sys.path[0])'"
fi

Note on misleading ImportError messages (issue #781): A bare

except ImportError can fire for transitive failures (e.g. a stray

/tmp/bisect.py shadowing stdlib bisect) unrelated to claude_mpm

itself. Always inspect the actual exception — e.name tells you

which module failed. If e.name does not start with claude_mpm, the

problem is a shadowed or missing transitive dependency, not a missing

claude_mpm installation.

Session Storage Location

Session location: project-local .claude-mpm/sessions/session-*.md (and .json)

Sessions are stored relative to the project root so each project has its own isolated session history. Resume always validates that the session belongs to the current project — you will never accidentally load a session from another checkout.

The store contains:

<project-root>/.claude-mpm/sessions/
├── LATEST-SESSION.txt                  # Pointer to most recent session
├── session-YYYYMMDD-HHMMSS.md          # Human-readable
└── session-YYYYMMDD-HHMMSS.json        # Machine-readable (loaded by resume)

Resume reads the .json file (authoritative machine-readable format). The .md file is for humans; resume will not attempt to parse it as JSON.

Token Budget

Token usage: ~20-40k tokens (10-20% of context budget)

This loads the session summary, accomplishments, next steps, git history, and pending task list into context so the PM can continue work without rediscovering state.

What Gets Loaded

From the paused session:

• Session ID and pause timestamp
• Project path (recorded at pause time, for display only)
• Git branch, recent commits, and file status at pause
• Summary, accomplishments, and next steps
• TaskList state (pending/in-progress tasks)
• Context message (if provided at pause)

Calculated at resume time:

• Human-readable time elapsed (e.g., "2 hours ago", "3 days ago")
• Git commits added since pause
• File changes since pause

Notes

• Reads existing sessions only. Does NOT create new files.
• Session pause is manual-only via /mpm-session-pause skill; this skill loads them.
• Session files are kept after resume (not auto-deleted) so you can resume multiple times.

Differentiating from Native Claude Code Resume

This skill is fundamentally different from Claude Code's native claude --resume/--continue and checkpoint-rewind (Esc-Esc / /rewind):

• Native `claude --resume`/`--continue`: Replays the full raw conversation transcript (persisted to a JSONL file on disk) and continues the exact same conversation thread, typically scoped to the same working directory. This is not ephemeral — the transcript survives the tool exiting.
• `/mpm-session-pause` + `/mpm-session-resume`: Captures a condensed textual summary (git state, todos, task list, accomplishments) into .claude-mpm/sessions/*.json files, loaded into a brand-new conversation rather than replaying the transcript. Useful for cross-project handoff, long-form work spanning many separate conversations, or a fresh context window with just the essential summary instead of the full raw history.

Related Commands

• /mpm-session-pause — Pause current session and save state
• claude-mpm session pause — CLI entry point for pause
• claude-mpm session resume --help — Full CLI usage

See the "Context Usage Monitoring" section of the mpm-session-management skill for how context-usage thresholds and warnings work (session pause is manual-only; there is no auto-pause).