claude-sessions

name	claude-sessions
description	Find a past Claude Code session on this machine by project or topic, then summarize what was done in it. Use when the user asks "which session did I do X in", "find the session where I worked on Y", "in project ~/path I worked on Z — find and summarize that session", "what was I doing in <project> last week", or wants to locate/recall/analyze a previous Claude Code conversation. Reads local ~/.claude/projects transcripts. Not for searching code, git history, or the current live session.
allowed-tools	Bash, Read, Agent, Task

Claude Sessions

Locate the past Claude Code session(s) matching a project and/or topic, then summarize them. Sessions are local JSONL transcripts; individual files reach tens of MB. Never read full transcripts into the main context — rank cheaply, then dispatch one subagent per top candidate to do the heavy read in isolation.

Storage facts

• Path: ~/.claude/projects/<dashified-cwd>/<sessionId>.jsonl. The dir name is the project's cwd with every / and . replaced by - (e.g. ~/workspace/OpenClawBot → -Users-engineer-workspace-OpenClawBot).
• One project may have sibling dir variants (…-OpenClawBot, …-OpenClawBot-2) — always consider all of them.
• Each line is a JSON record with a type: user, assistant, custom-title (customTitle), last-prompt (lastPrompt), summary, file-history-snapshot, etc. Records carry an ISO timestamp.

Procedure

1. Rank candidates cheaply. Run the bundled ranking script (scripts/rank_sessions.py, next to this SKILL.md) — never grep raw transcripts yourself first.

python3 <skill-dir>/scripts/rank_sessions.py [--project PATH] [--days N] [--limit N] KEYWORD...
# installed location is usually:
python3 ~/.claude/skills/claude-sessions/scripts/rank_sessions.py --project ~/workspace/OpenClawBot "merge gate" enforce testing

• Give --project when the user names a path or project; omit it to search every project by topic.
• Pass the user's topic as several keyword variants ("merge gate" "PR gate" enforce testing) — more matching keywords ranks a file higher.
• Output is JSON: ranked candidates with session_id, path, date, title, last_prompt, first_user, and keyword hit counts.

2. Deep-read the top candidates with subagents — in parallel. Dispatch the top 2–4 candidates (one Agent/Task call each, in a single message so they run concurrently). This keeps multi-MB transcripts out of your context. Each subagent prompt must:

• Name the exact path.
• Instruct it to grep within the file for the topic keywords and read only the surrounding context lines (e.g. grep -n -i 'merge gate' FILE, then extract user/assistant text near those lines). Forbid reading the whole file.
• Return a compact report: does this session match the topic (yes/no + confidence), a 3–6 sentence summary of what was done, key files/PRs/commands touched, and the session date + id.

Subagent prompt: "Read the Claude Code transcript at (JSONL, possibly tens of MB — do NOT read it whole). The user is looking for the session where they worked on **PR merge-gate enforcement testing**. Use `grep -n -i` for 'merge gate', 'merge-gate', 'enforce', 'required check', 'branch protection' to find relevant lines, then read only the nearby `user`/`assistant` text records. Report: MATCH yes/no + confidence; a 3–6 sentence summary of what was actually done; key files/PRs/commands; and the session id + date. Keep under 200 words."

3. Present the best match. Lead with the winning session — its summary, session_id, path, and date. List runner-up candidates as one line each (id, date, why weaker). If nothing matches, say so and show the top recent sessions for the project so the user can redirect.

Notes

• summary/custom-title lines are sparse; rank also uses whole-file keyword hit counts, so a high keyword_file_hits with zero meta matches is still a strong signal.
• Browse mode: run the script with no keywords (optionally --days 7) to list recent sessions when the user is vague ("what was I doing in X lately").
• To resume a found session, tell the user the id — claude --resume <session_id>.

Done when

The user has the matching session's id, path, date, and a summary of what was done there — produced via subagent reads, with the main context never having ingested a full transcript.