cc-session-search

name	cc-session-search
description	Search Claude Code conversation history. Use when user asks "where did I discuss X", "when did we talk about X", "find the conversation about X", or wants to continue previous work.

Session Search

Search and analyze Claude Code conversation history.

For storage internals (sessions-index.json, /rename scope, path encoding): See cc-internals skill.

Quick Reference

Fact	Value
Sessions location	~/.claude/projects/<encoded-path>/
Session format	JSONL (one JSON object per line)
Main sessions	<uuid>.jsonl
Subagent sessions	agent-<hash>.jsonl

Tool Selection

Task	Use This	NOT This
Pattern search	CC Grep tool	rg via Bash
Read files	CC Read tool	cat via Bash
Find files	CC Glob tool	find via Bash
JSON extraction	jq via Bash	(no CC equivalent)

Why CC tools: Better permissions, structured output, error handling. Why Bash for jq: No native JSONL parsing in CC.

JSONL Message Structure

{
  "type": "user" | "assistant" | "summary",
  "timestamp": "<ISO-8601>",
  "message": { "content": [{ "type": "text", "text": "..." }] },
  "uuid": "<uuid>",
  "sessionId": "<uuid>"
}

Search Approach

Step 1: Use CC Grep tool to find matching sessions

Grep pattern="X" path="~/.claude/projects/" output_mode="files_with_matches"

Step 2: Use Bash + jq for JSON extraction

jq -c 'select(.type=="user") | select(.message.content[].text | test("pattern";"i"))' file.jsonl

Step 3: Use CC Read tool to examine specific session content

Query Workflows

"Where did I discuss X?"

1. Grep tool → find matching session files
2. Decode paths to project names
3. Bash + jq → extract first timestamp + context
4. Report: project, session ID, date range, snippet

"When did we discuss X?"

1. Grep tool → find matching files
2. Bash + jq → extract timestamps from matches
3. Report: timeline grouped by date/project

"Continue work on X"

1. Grep tool → find sessions mentioning X
2. Read tool → examine most relevant session
3. Analyze: goal, accomplishments, pending items, decisions
4. Generate continuation prompt (see template below)

Continuation Prompt Template

Continuing work from [date] on [project]:

## Original Goal
[from first user message]

## What Was Done
- [accomplishments]
- [files changed]

## Pending
- [incomplete items]

## Key Decisions
- [choices that carry forward]

## Resume Point
[specific next task]

jq Patterns

# Decode project path (inline)
echo "-Users-foo-bar" | sed 's/^-/\//; s/-/\//g'

# Extract timestamps from session
jq -r '.timestamp // empty' file.jsonl | sort

# User messages only
jq -c 'select(.type=="user")' file.jsonl

# Filter by text content
jq -c 'select(.message.content[].text | test("pattern";"i"))' file.jsonl

# Get first/last timestamp
jq -rs '[.[].timestamp | select(.)] | sort | .[0], .[-1]' file.jsonl

Related Skills

Topic	Skill
Storage internals, /rename	cc-internals
Permission config	cc-configuring-permissions