find-session - SKILL.md Agent Skill

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:

# <project description> — resume specific session
<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.