From session-finder
Use when the user wants to find, list, or recover a PAST Claude Code session — "list my sessions", "find that session where I worked on X", "what did I do yesterday in the dotfiles repo", "I had a long chat about JWT auth last week, can you find it", "resume the autonomo eval session", "I deleted that worktree, how do I get back into the conversation". Fires on natural phrasing — the user names what they remember (date, repo, branch, topic, what they typed) without having to recall the session ID. Also fires for orphaned worktrees the user wants to recreate, and for plain non-worktree sessions. Do NOT trigger for stats about THIS session (cost, tokens, runtime — that's the session-stats skill), for `claude -c` style "continue the most recent session in this dir" (built-in), or for general shell history / git log style questions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/session-finder:session-finderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
List, search, and recover past Claude Code sessions stored on disk.
List, search, and recover past Claude Code sessions stored on disk.
Sessions live in ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl — one
file per session, one JSON event per line. The user usually doesn't
remember the UUID; they remember the topic, the repo, or roughly when.
This skill bridges that gap.
The user is looking for a session that already happened. Common shapes:
session-stats skill.claude -c (built-in), no skill needed.Quick orientation so the output makes sense:
~/.claude/projects/<slug>/. The slug
is the cwd with / and . both replaced by - (so /. becomes
--).<uuid>.jsonl.user, assistant, system, attachment,
last-prompt, permission-mode, file-history-snapshot. The
cwd, gitBranch, timestamp, and version fields appear on
every user/assistant/system event — the original working
directory and branch are preserved verbatim, no decoding needed.last-prompt events store the most recent user prompt as a
top-level lastPrompt field — that's the cheapest way to get a
one-liner for a session.system events with subtype: away_summary are Claude's own
summary of what happened. Use as the description if present.There's one bundled script that does discovery, parsing, filtering, and command generation. Don't reinvent it inline — just call it.
python3 <skill-dir>/scripts/list_sessions.py [filters]
<skill-dir> is the directory containing this SKILL.md.
Read the request and decide which flags to pass. Combine freely.
| User says | Flag |
|---|---|
| "in gruppo", "in ~/code/dotfiles" | --dir <substring> |
| "yesterday", "last week", "since Apr" | --since YYYY-MM-DD (and/or --until) |
| "on the autonomo branch", "worktree X" | --branch <substring> |
| "about JWT auth", "where I touched X" | --keyword "<phrase>" (slower) |
| "the orphaned ones", "deleted worktrees" | --only-orphaned |
| "worktree sessions", "tmp dirs" | --only-worktrees |
| "more results", "show me all" | --limit <N> (default 50) |
Convert relative dates to absolute before passing (yesterday →
today's date minus 1, etc.). The script accepts YYYY-MM-DD or full
ISO timestamps — not "yesterday".
Default output is a compact table sorted by recency:
ID AGE WHERE MSGS SIZE PROMPT
-------- ------- --------------------------------- ---- ---- --------
3627ee4f 7m ago ~/code/gruppo (gemini-search-…) 91 215K I was recovering this repo from…
7d7ed71b 1d ago gruppo:autonomo-eval-more [orph] 1317 4.8M ! pwd
0851889c 23h ago dotfiles:abd [orph] 25 72K curl script
Reproduce the table verbatim. The columns are short on purpose — they're meant to fit in a terminal pane.
Markers in the WHERE column:
repo:branch [wt] — worktree session, directory still existsrepo:branch [orph] — worktree session, directory deleted<path> [missing] — plain (non-worktree) directory, no longer existsA keyword search will often return multiple sessions that all contain the phrase — same word lives in different conversations. Don't just pick the top hit. The user described a topic; that topic lives in the content of the session, not just the keyword density.
When the table has more than one candidate that plausibly fits:
--inspect on each top candidate (cheap — it's already parsed).Why: keyword presence is a coarse filter. A session about "session-stats
the skill" and a session about "lines-of-code in session-stats" both
match --keyword session-stats, but only one matches the user's intent.
Mismatching here wastes the user's time and (if they actually run the
resume command) drops them into the wrong context.
Inspect by short ID (the 8-char prefix from the table) or by full UUID:
python3 <skill-dir>/scripts/list_sessions.py --inspect <short-id>
The detail view includes the full UUID, file path, byte size, message counts, original cwd, git branch, version, first event timestamp, last event timestamp, the first user prompt, the last user prompt (if different), the away summary (if present), and a resume command tailored to the session's situation.
The script picks the right command based on three cases. Pass it through to the user as-is — they will run it themselves; do not run it for them, because resuming a session inside another Claude Code session would either spawn a child process or exit the current one.
Cases the script handles:
cd <cwd> && claude --resume <uuid>wt switch <branch> && claude --resume <uuid> — wt switch is
preferred over cd because of worktrunk hooks (post-start
copies gitignored content like .superpowers/, .autonomo/,
.claude/settings.local.json into the worktree). Plain cd skips
those.wt switch --create <branch> && claude --resume <uuid>. The script
notes that this must run from inside the parent repo so wt knows
which repo to recreate the worktree against. As long as the branch
name is the same, the recreated worktree path encodes to the same
slug, so Claude Code finds the existing session file.Everything above also works for plain-directory sessions. The skill
shouldn't push worktree workflows on a user who isn't using them. If
no [wt] markers appear in the listing, just present the cd …
resume commands. Likewise, if wt isn't installed and the user wants
to resume a worktree session, fall back to cd <cwd> && claude --resume <uuid> — it'll work; it just skips the worktrunk hooks.
--dir <substring>Substring match against the original cwd (case-insensitive). Useful
because the cwd is the truth — encoded slug names are noisy.
--branch <substring>Matches against the git branch and the worktree name (the segment after
/.claude/worktrees/ in the path). So --branch autonomo finds both
sessions on the autonomo branch and worktrees named autonomo-eval.
--keyword "<phrase>"Full-text scan of the JSONL bodies. Slower (reads every line of every session) but catches things the metadata filters miss. The output adds a "Keyword matches" section showing a snippet around each hit. Use sparingly — for a focused dir/branch first, then keyword.
--since / --untilFilter by file mtime (last activity). Accept YYYY-MM-DD or full ISO
timestamps. mtime is a good proxy for "when I was last in this
session" because every event appended to the JSONL bumps it.
--only-orphanedOnly sessions whose original cwd no longer exists on disk. The recovery candidates the user usually cares about.
--only-worktreesOnly sessions whose cwd lives under /.claude/worktrees/.
--limit <N>Hard cap on rows in the table. Defaults to 50. The script reports how many were truncated.
--format jsonSame data, machine-readable. Useful if the user wants to pipe through
jq or build a shell pipeline.
Reproduce the script's output verbatim — don't reformat the table or
re-summarize the inspect view. The widths are tuned for terminal
display, and rewording loses signal (esp. the [wt] / [orph] /
[missing] markers).
If many sessions match, lead with the table, then offer to narrow:
"Want me to filter by branch, date, or content?" Don't paginate or
dump 1000 rows by default — --limit 50 is usually plenty.
"What was I working on yesterday?"
python3 <skill-dir>/scripts/list_sessions.py --since 2026-05-06 --until 2026-05-06
(Translate "yesterday" to today minus 1.)
"Find the session about session-stats triggering."
python3 <skill-dir>/scripts/list_sessions.py --keyword "session-stats triggering"
If no hits, broaden: drop a word, try synonyms (the user remembers the gist, not their exact phrasing).
"I removed the autonomo-eval-more worktree, can I get it back?"
python3 <skill-dir>/scripts/list_sessions.py --only-orphaned --branch autonomo-eval-more
Then --inspect <short-id> to get the wt switch --create resume
command.
"List the longest sessions in the gruppo repo."
The script doesn't sort by size, but --format json + jq handles it:
python3 <skill-dir>/scripts/list_sessions.py --dir gruppo --format json \
| jq 'sort_by(-.size_bytes) | .[:10]'
cd to a different absolute path and run
claude --resume <uuid>, it won't see the session. The resume
commands the script generates respect this — don't rewrite them.--inspect (first event).usage blocks; that's the
session-stats skill's job. This skill stops at message counts.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub martinciu/gruppo --plugin session-finder