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 |