resume-claude-session

name	resume-claude-session
description	Use when the user asks Codex to continue, resume, or take over work from a Claude Code session by session name or session id (UUID or UUID prefix). Examples include "continue the claude session called feature-x" or "/resume-claude-session a3b5c9f2". Do not use for ordinary Codex resume commands or when the user only asks about Codex's own session history.

Resume Claude Code session

Purpose

When Codex takes over work from a Claude Code session, reconstruct the current state by reading both the Claude storage and the actual working directory. Do not hand off based on only the last few conversation lines.

Procedure

1. Determine the query.

   • Input is a session name (e.g. feature-x) or a session id (UUID or UUID prefix, e.g. a3b5c9f2). Optionally a working-directory or project hint from the user.
   • If the query looks like a UUID (8+ hex, dashes allowed), go straight to the id lookup path — it matches on the filesystem and works even when the session is not in the live index.
   • Otherwise, use the name path. claude feature-x means feature-x.
   • If several names are plausible, confirm briefly once before a wider search.

2. Find session candidates.

uv run python <skill-dir>/scripts/find_claude_session.py <session-name-or-id>
uv run python <skill-dir>/scripts/find_claude_session.py <session-name-or-id> --cwd-hint <expected-path>
uv run python <skill-dir>/scripts/find_claude_session.py <session-name-or-id> --json      # structured output for programmatic picking

• If uv is missing, fall back to python3, then python. If none are available, tell the user "Python 3 required — install from python.org" and stop.
• If the helper is missing, rg "(customTitle|agentName)":"<name>" over ~/.claude/projects ~/.claude/history.jsonl, or for a UUID, rglob ~/.claude/projects/**/<uuid>.jsonl.
• Each helper supports --help for the full flag reference (precedence rules, score weights, edge cases).

3. Pick the most likely candidate.

   • Prefer the candidate with the highest helper score (exact name match > exact id match > id prefix match).
   • On ties, prefer candidates matching the user's cwd/project hint.
   • Still tied? Prefer the most recent updatedAt or timestamp.
   • Still ambiguous? Show the top candidates and ask which session to take over.

4. Locate the transcript and task files.

SESSION_ID=<found-session-id>
find ~/.claude/projects -name "${SESSION_ID}.jsonl" -print
find ~/.claude/tasks/"${SESSION_ID}" -maxdepth 1 -type f | sort -V

5. Skim the task files before the transcript.
   • Task files usually show the work map and open points faster than the transcript.
   • Read enough to describe the goal, artifacts, blocking point, and modified files.

for f in ~/.claude/tasks/"${SESSION_ID}"/*.json; do
  printf '\n## %s\n' "$f"
  sed -n '1,160p' "$f"
done

6. Read the transcript in bounded windows. Do not dump whole JSONL lines — one line can be several KB.
   • Capture: original goal, mid-session scope changes, created/modified files, commits, failed tests, errors, last user request, last tool result, cwd changes.
   • Read head first (goal + initial user turn + cwd), then tail (recent state). Skip the middle unless you need a pivot.

TRANSCRIPT=<found-transcript-jsonl>
uv run python <skill-dir>/scripts/summarize_claude_transcript.py "$TRANSCRIPT" --tail 0 --max-events 40     # head: goal, first user message, initial cwd
uv run python <skill-dir>/scripts/summarize_claude_transcript.py "$TRANSCRIPT" --tail 120                   # tail: recent state
uv run python <skill-dir>/scripts/summarize_claude_transcript.py "$TRANSCRIPT" --from-line <N> --max-events 80   # pivot: specific error/turn

• --limit caps chars per event (default 700). If a tool result or assistant message looks truncated mid-diff or mid-error, re-run the same window with --limit 2000.
• If the helper is missing, use rg -n --only-matching for line numbers and short matches, then open small windows with sed -n '<start>,<end>p'. Never print entire JSONL matches.

7. Re-verify the actual working directory state.
   • Do not trust the transcript for package installs, created files, test results, branch, or git status.
   • From the actual cwd (confirmed from the transcript), run:

git status --short
git log --oneline -15
git worktree list

• If it is not a git repo, say so and verify via the filesystem instead.

8. Before changing any files, build a short handoff summary:

   • Session name and sessionId
   • Actual working directory and branch
   • The user's original goal
   • What is already done
   • The blocking point and any open risks
   • The first command or file to resume with

9. Only resume work from a verified state.

   • If the next step is clear and low-risk, proceed after presenting the handoff summary.
   • If the state is ambiguous, do not guess — ask the decision you need.

Notes

• Do not record the latest state of a specific session into AGENTS.md or this skill.
• Do not revert or overwrite changes in the actual working directory unless the user explicitly asks.
• Treat created files, installed packages, and test results as stale until re-confirmed on disk.