| name | find-session |
| description | Identify a specific Claude Code conversation by its UUID and optionally pin it as a shell function for one-word resume. Use when "claude --continue" picks the wrong session, or when the user wants to reliably resume a specific past conversation across reboots. |
find-session — pin a specific Claude conversation
claude --continue picks "most recent in cwd" — unreliable when multiple
sessions share a directory. claude --resume <uuid> is exact. This skill
finds the right UUID by grepping jsonl files, then writes a one-word shell
function so the user types e.g. aichain to resume that exact conversation.
When to use
- User says "I can't find my session" / "claude --continue picks wrong one"
- User wants a one-word resume command for a specific long-running conversation
- Multiple
.jsonl files in ~/.claude/projects/<encoded-cwd>/ exist
Workflow
1. Find the encoded-cwd directory
Sessions are stored under ~/.claude/projects/<encoded-cwd>/. The encoding
replaces / with -, so cwd /Users/foo/Desktop/MyProj becomes
-Users-foo-Desktop-MyProj. Often the cwd at session-start was the user's
HOME, even if work happened in a subdirectory.
If unsure which encoded-cwd to scan:
ls -dt ~/.claude/projects/*/ | head -5
The most recently modified directory is likely the right one.
2. List active session files
ls -lt ~/.claude/projects/<encoded-cwd>/*.jsonl 2>/dev/null | head -10
Multiple files = multiple sessions. The biggest by size is NOT
necessarily the right one — both the current assistant and other parallel
sessions can be wrong about that.
3. Get a unique-content hint from the user
Ask: "What's something only this conversation would contain? A specific
filename you created, a unique tool you ran, a project name, etc."
Good hints (highly unique):
- A hostname / URL the conversation generated (e.g.
waqvu5.png)
- A file path that was created by this session (e.g.
kimi_research_results)
- A specific function name written in this session (e.g.
compute_factor_scores)
- A unique error message they remember
Bad hints (too common, will match multiple):
- Generic words like "Python", "test", "fix"
- Common library names
4. grep to find matching session
for f in ~/.claude/projects/<encoded-cwd>/*.jsonl; do
echo "=== $(basename "$f") ==="
grep -c "<unique-string>" "$f" 2>/dev/null
done
The session with non-zero hits (ideally many hits) is the answer. Confirm
with 2-3 different unique strings if the first match is ambiguous.
5. Offer to pin as shell function
Once UUID is identified, ask user for a short name (e.g. aichain,
work, headsup). Then append to ~/.zshrc:
<short-name>() {
cd "$HOME" && claude --resume "<uuid>"
}
cd "$HOME" matters: sessions are indexed by their starting cwd, so the
alias must cd to the same place where the session was originally created
(often HOME, even if the actual work touched subdirectories).
After write, tell user to either:
- Run
source ~/.zshrc in current terminal, OR
- Open a new terminal
Important notes
- Each
.jsonl is the full transcript log of one session. Sizes can mislead;
always rely on grep'd content matches, not file size.
- The UUID is stable forever — once pinned, the alias keeps working across
reboots, OS upgrades, even years (assuming the .jsonl isn't deleted).
- If user has multiple long-running parallel sessions (e.g., two different
projects, both started from HOME), each needs its own pin. Repeat the
workflow once per session.
- Don't confuse session UUIDs across different conversations. If two Claude
instances both claim the same UUID, at least one is wrong — only grep on
actual unique content can verify.
Quick check
After pinning, verify:
source ~/.zshrc && type <short-name>
Should show the function definition.
