Claude code sessions

Claude Code Sessions

Reads Claude Code session files from ~/.claude/projects/ to search, analyze, and manage session history. For users who want to find past work, understand token and tool usage, recover context for a session, or clean up stale tasks.

When to use

• User asks to search or find something across past Claude Code sessions, optionally within a date range.
• User asks for session statistics: token usage, model distribution, tool call breakdowns.
• User asks to list sessions, sorted by recency, size, or duration, possibly with a limit.
• User gives a session ID and wants to resume or recover context from it.
• User asks about pending or orphaned tasks across sessions, or wants to delete sessions or tasks.

Workflows

Search sessions

Inputs: Search query; optional date range.

1. Read session files under ~/.claude/projects/.
2. Run full-text search across all session files for the query.
3. If a date range was given, filter matches by session timestamps.
4. Track which sessions have already been searched and skip re-scanning unchanged files.
5. Return each matching session with context snippets around the match.

Check: Every returned match comes from an actual session file; no matches are invented. Output: List of matching sessions with context snippets, plus session ID, date, and project for each.

Show session statistics

Inputs: None beyond the request; read all session files.

1. Read all session files under ~/.claude/projects/.
2. Compute token usage totals, model distribution, and tool call breakdowns.
3. Report the numbers exactly as computed.

Check: Figures match the files exactly; nothing rounded or estimated. Output: Token totals, model distribution, and tool call breakdowns. If no sessions exist, state that plainly.

List sessions

Inputs: Sort key (recency, size, or duration); optional limit.

1. Read all session files under ~/.claude/projects/.
2. Sort by the requested key.
3. Apply the limit exactly if one was given.
4. Build a table with session ID, date, project, token count, and duration.

Check: Row count respects the limit; sort order matches the request. Output: Table of sessions with session ID, date, project, token count, and duration.

Resume a session

Inputs: Session ID.

1. Read that session file.
2. Summarize the conversation, active tasks, and last state.
3. Generate a context recovery prompt from that summary.
4. Do not modify any files.

Check: The prompt reflects only what is in the session file. Output: A draft context recovery prompt presented for the user to copy.

Manage tasks across sessions

Inputs: Request for tasks, or a deletion request.

1. Scan all session files for pending and orphaned tasks.
2. Group tasks by status and project.
3. If the user wants to delete sessions or tasks, confirm the action first and proceed only after explicit approval.

Check: No deletion happens without explicit confirmation. Output: Tasks grouped by status and project; deletions only after approval.

Tools and data

• Use local filesystem access to ~/.claude/projects/ when available; if it is not available, ask the user to provide the session files or connect the directory.

Guardrails

• Never modify or create session files — only read, and delete only when explicitly approved.
• Never delete sessions or tasks without asking for confirmation first.
• Never estimate or round token counts or statistics — report exact figures from the files.
• If no sessions are found, say so plainly. Never invent sessions or fabricate data.

Getting started

Ask the user what they want to do: search sessions, view stats, list sessions, resume a session, or manage tasks. If they want to search, ask for a query and an optional date range.

Credits

Adapted from an open-source original (MIT): https://www.aitmpl.com/component/skills/productivity/claude-code-sessions