Finding a past session
The user remembers a session by what happened in it — "there was a
session where I was exploring…" — and wants it back. Its name is a weak
index: Claude Code titles a session once, from its first prompt, so one
that wandered keeps the title of where it began (each of 233 titled
sessions held exactly one title, 2026-10-06). The bundled script reads
the words instead, in every transcript under ~/.claude/projects/, from
every repo on this machine.
1. Search
uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/find-session.py <term> <term> ...
- Every term must appear in the session, as a substring, ignoring
case: in its name, a prompt the user typed, or a compaction summary.
Take two or three of the user's own distinctive words, not a
paraphrase; a common word matches most of the store. Words given after
find-session are the terms.
- Keep
--no-project. Without it, uv run in a repo that has its
own Python project syncs that project first. The script needs no
dependencies.
- Drop a leading
/. Git Bash rewrites /<name> into
C:/Program Files/Git/<name> before the script sees it, quoted or
not, and the search answers 0 of … sessions matched, exit 1, which
reads as an honest miss (2026-10-06). The script records a typed
command as /<name> <args>, so <name> finds it.
PowerShell passes the slash intact.
2. Read the hits
2026-09-29 23:18 my-repo contributing-md
prompt: …ood point. I always wanted to rename and group my Claude Code sessions to keep better track of them. Is there …
claude --resume 053abce6-857e-4d2b-b5d8-77150b3e4e75
12 of 212 sessions matched, first 2 shown; oldest transcript written 2026-09-29; times are local
- The first line is the last activity in local time, the repo (the
folder the session ran in, a worktree counted as its repo) and the
session's name: one set by
/rename, -n or a hook, else Claude
Code's title, else the start of the first prompt.
- The second says where every term met:
name, prompt, summary
or reply. some terms; the rest elsewhere means no one passage holds
them all and the session matched only as a whole, which a long
compaction summary makes common: a weak hit.
- The first hit is the tightest, not the newest. Hits rank by where
every term met, a name, then one prompt, one summary, one reply, then
scattered, and newest first within each.
- The asking session is left out. Its own prompt holds the terms, so
the script drops the transcript
CLAUDE_CODE_SESSION_ID names, which
Claude Code sets in both its shells (2026-10-06).
- The last line gives the reach: the day the oldest transcript on
disk was last written. That bounds a transcript's last write, not its
session's last activity: Claude Code writes title and state records
after a session's last prompt, so a hit can predate the reach, as one
last active 2026-09-24 did beside a reach of 2026-09-29 (2026-10-06).
3. Narrow or widen
--repo <folder> keeps one repo, by its folder name; its worktrees
count as it.
--days <n> keeps transcripts written in the last n days.
--limit <n> shows n hits, 10 by default; the last line counts them
all.
--replies searches Claude's text too, for what Claude said rather
than what the user typed.
--probes brings back probe sessions, left out by default: a working
directory in the temp folder, or a name starting probe:.
--json prints the hits for parsing: session_id, title, repo,
cwd, branch, first_active, last_active, match and resume.
Its stamps are UTC, where the text's times are local, and it prints no
reach.
4. When nothing matches
Exit 1 with 0 of … sessions matched is a miss. Before calling the
session lost:
- Retry with fewer terms, or the user's other words for the subject; a
word only Claude used needs
--replies.
- Add
--probes if it may have been a test run.
- Then read the reach. A session last active before the summary's
date is most likely gone, but not certainly, since the date bounds the
oldest transcript's last write, not its last activity (§2): say it is
most likely gone, and why. Claude Code deletes transcripts older than
cleanupPeriodDays, 30 days by default, and the store can hold less
than the setting says once a lower value has run: 7 days against 15 on
2026-10-06, after the setting had been turned down for a while. Do not
search the transcripts by hand.
Exit 2 has two meanings, told apart by stderr. the transcript format may have changed means the script read transcripts and found not one
prompt in them, which is how a release changing Claude Code's internal
transcript format shows. Report that, and do not grep the transcripts as
a stand-in.
A usage: line means a bad flag. no transcripts under <path>, exit 1,
means the store is empty.
5. Report
- The top hit or two: name, repo, last activity, the passage that
matched, and its
claude --resume <id>. Say so when the best hit is
only scattered.
claude --resume <id> works from any folder: Claude Code looks in
the current project and its worktrees, then every other project on
this machine (2.1.223 or later). Whether VS Code opens a session by its
id was not checked (2026-10-06).
- Never Read a transcript whole to answer from it. It holds every
tool result: on 2026-10-06 the median was 623 KB and the largest
36.6 MB. To learn what a session concluded, search again with
--replies and words from the answer, or resume it.
Constraints
- Reads only. This skill renames, resumes and deletes no session.
- Not this skill: naming the current session is
/rename. Live
sessions are ListAgents from inside a session, and background ones
claude agents from a terminal, whose n:<text> filter (2.1.287) and
Ctrl+F match names and tasks, not what was said.
- Out of reach: subagent transcripts, under
<project>/<session>/subagents/, which the script does not read, and
any session whose transcript is not under ~/.claude/projects/ on this
machine, such as a cloud session's.
1---2name: find-session3model: inherit4effort: high # runs a bundled script and reports it; tiers in editing-skills.md5disable-model-invocation: false6argument-hint: "[words from the session]"7allowed-tools: Bash(uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/find-session.py *)8description: "Finds a past Claude Code session by what was said in it — words from a prompt the user typed, a compaction summary or the session's name — across every repo on this machine, and gives the claude --resume command that reopens it. Runs the script bundled with the skill over the transcripts on disk, ranks one prompt holding every term above terms scattered through a long session, and reports how far back the transcripts reach, since an older session is gone. Naming the current session is /rename; running and background sessions are claude agents."9when_to_use: "Use when the user recalls an earlier session, conversation or chat by what was in it and wants it back — 'there was a session where I was exploring…', 'find the conversation where we decided X', 'which session did I do Y in', 'reopen the one about Z' — or needs a past session's id to resume it."10metadata:11 source: https://skillmd.com/skills/wardawgmalvicious/find-session12---1314# Finding a past session1516The user remembers a session by what happened in it — "there was a17session where I was exploring…" — and wants it back. Its name is a weak18index: Claude Code titles a session once, from its first prompt, so one19that wandered keeps the title of where it began (each of 233 titled20sessions held exactly one title, 2026-10-06). The bundled script reads21the words instead, in every transcript under `~/.claude/projects/`, from22every repo on this machine.2324## 1. Search2526```bash27uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/find-session.py <term> <term> ...28```2930- **Every term must appear in the session**, as a substring, ignoring31 case: in its name, a prompt the user typed, or a compaction summary.32 Take two or three of the user's own distinctive words, not a33 paraphrase; a common word matches most of the store. Words given after34 `find-session` are the terms.35- **Keep `--no-project`.** Without it, `uv run` in a repo that has its36 own Python project syncs that project first. The script needs no37 dependencies.38- **Drop a leading `/`.** Git Bash rewrites `/<name>` into39 `C:/Program Files/Git/<name>` before the script sees it, quoted or40 not, and the search answers `0 of … sessions matched`, exit 1, which41 reads as an honest miss (2026-10-06). The script records a typed42 command as `/<name> <args>`, so `<name>` finds it.43 PowerShell passes the slash intact.4445## 2. Read the hits4647```text482026-09-29 23:18 my-repo contributing-md49 prompt: …ood point. I always wanted to rename and group my Claude Code sessions to keep better track of them. Is there …50 claude --resume 053abce6-857e-4d2b-b5d8-77150b3e4e755112 of 212 sessions matched, first 2 shown; oldest transcript written 2026-09-29; times are local52```5354- **The first line** is the last activity in local time, the repo (the55 folder the session ran in, a worktree counted as its repo) and the56 session's name: one set by `/rename`, `-n` or a hook, else Claude57 Code's title, else the start of the first prompt.58- **The second says where every term met**: `name`, `prompt`, `summary`59 or `reply`. `some terms; the rest elsewhere` means no one passage holds60 them all and the session matched only as a whole, which a long61 compaction summary makes common: a weak hit.62- **The first hit is the tightest, not the newest.** Hits rank by where63 every term met, a name, then one prompt, one summary, one reply, then64 scattered, and newest first within each.65- **The asking session is left out.** Its own prompt holds the terms, so66 the script drops the transcript `CLAUDE_CODE_SESSION_ID` names, which67 Claude Code sets in both its shells (2026-10-06).68- **The last line gives the reach**: the day the oldest transcript on69 disk was last written. That bounds a transcript's last write, not its70 session's last activity: Claude Code writes title and state records71 after a session's last prompt, so a hit can predate the reach, as one72 last active 2026-09-24 did beside a reach of 2026-09-29 (2026-10-06).7374## 3. Narrow or widen7576- `--repo <folder>` keeps one repo, by its folder name; its worktrees77 count as it.78- `--days <n>` keeps transcripts written in the last n days.79- `--limit <n>` shows n hits, 10 by default; the last line counts them80 all.81- `--replies` searches Claude's text too, for what Claude said rather82 than what the user typed.83- `--probes` brings back probe sessions, left out by default: a working84 directory in the temp folder, or a name starting `probe:`.85- `--json` prints the hits for parsing: `session_id`, `title`, `repo`,86 `cwd`, `branch`, `first_active`, `last_active`, `match` and `resume`.87 Its stamps are UTC, where the text's times are local, and it prints no88 reach.8990## 4. When nothing matches9192Exit 1 with `0 of … sessions matched` is a miss. Before calling the93session lost:9495- Retry with fewer terms, or the user's other words for the subject; a96 word only Claude used needs `--replies`.97- Add `--probes` if it may have been a test run.98- **Then read the reach.** A session last active before the summary's99 date is most likely gone, but not certainly, since the date bounds the100 oldest transcript's last write, not its last activity (§2): say it is101 most likely gone, and why. Claude Code deletes transcripts older than102 `cleanupPeriodDays`, 30 days by default, and the store can hold less103 than the setting says once a lower value has run: 7 days against 15 on104 2026-10-06, after the setting had been turned down for a while. Do not105 search the transcripts by hand.106107Exit 2 has two meanings, told apart by stderr. `the transcript format108may have changed` means the script read transcripts and found not one109prompt in them, which is how a release changing Claude Code's internal110transcript format shows. Report that, and do not grep the transcripts as111a stand-in.112A `usage:` line means a bad flag. `no transcripts under <path>`, exit 1,113means the store is empty.114115## 5. Report116117- **The top hit or two**: name, repo, last activity, the passage that118 matched, and its `claude --resume <id>`. Say so when the best hit is119 only scattered.120- **`claude --resume <id>` works from any folder**: Claude Code looks in121 the current project and its worktrees, then every other project on122 this machine (2.1.223 or later). Whether VS Code opens a session by its123 id was not checked (2026-10-06).124- **Never Read a transcript whole** to answer from it. It holds every125 tool result: on 2026-10-06 the median was 623 KB and the largest126 36.6 MB. To learn what a session concluded, search again with127 `--replies` and words from the answer, or resume it.128129## Constraints130131- **Reads only.** This skill renames, resumes and deletes no session.132- **Not this skill**: naming the current session is `/rename`. Live133 sessions are `ListAgents` from inside a session, and background ones134 `claude agents` from a terminal, whose `n:<text>` filter (2.1.287) and135 Ctrl+F match names and tasks, not what was said.136- **Out of reach**: subagent transcripts, under137 `<project>/<session>/subagents/`, which the script does not read, and138 any session whose transcript is not under `~/.claude/projects/` on this139 machine, such as a cloud session's.