ccs — Claude Code Session Search

Fast full-text search across Claude Code session transcripts.

Features

• Fast: Uses ripgrep for file-level matching (~70ms across 1000+ sessions), then Python for structured filtering
• Filter by speaker: Search only your messages (--user) or Claude's responses (--assistant). The --user filter is smart — it excludes tool results (bash output, file reads) that are stored as user records in the JSONL format
• Filter by project: Narrow results to a specific project directory (--project)
• Filter by date: Only include recent sessions (--since)
• Zero dependencies: Python stdlib only. Auto-detects ripgrep (system install or Claude Code bundled binary), falls back to grep
• Color output: Highlights matches, color-codes speakers, shows session metadata
• JSON output: Machine-readable output for integration with other tools (--json)

Installation

# Clone the repo
git clone https://github.com/yourusername/claude-session-search.git
cd claude-session-search

# Option A: Symlink to your PATH
ln -s "$(pwd)/ccs" ~/.local/bin/ccs

# Option B: Copy the script
cp ccs ~/.local/bin/ccs
chmod +x ~/.local/bin/ccs

Optional: Install ripgrep for best performance

ccs works without ripgrep (falls back to grep), but ripgrep is ~20x faster:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Or: ccs auto-detects Claude Code's bundled ripgrep — no install needed

Usage

# Search all sessions
ccs "RabbitMQ"

# Only in your messages
ccs "backup script" --user

# Only in Claude's responses
ccs "docker compose" --assistant

# Filter by project
ccs "webhook" --project my-app

# Only recent sessions
ccs "deploy" --since 2025-03-01

# Show resume commands
ccs "auth fix" --verbose

# JSON output
ccs "migration" --json

Output

3 matches in 2 sessions

2025-03-28  migrate-webpay-checkout  [~/Sites/magento]
  [claude] 01:46  ...RabbitMQ exchange recreation after fresh container start...

2025-03-20  switch-production-vulcan-to-leti  [~/Sites/magento]
  [you] 14:00  ...Redis, OpenSearch, and RabbitMQ connection settings should match...
  [claude] 14:01  ...checking RabbitMQ configuration in app/etc/env.php...

How it works

1. Phase 1: ripgrep (or grep) scans all .jsonl files in ~/.claude/projects/ for the keyword — sub-100ms
2. Phase 2: Python parses matching files, filters by type/date, extracts context around matches
3. Metadata: Reads custom-title records for session names, falls back to first user prompt

Claude Code Skill

If you use Claude Code, you can create a skill that wraps ccs for natural language queries:

"Search my sessions for where I mentioned RabbitMQ"
"Find in your responses the backup script"
"Search in the lemps project for cron setup"

See the skill example for a ready-to-use skill definition you can drop into ~/.claude/skills/search-sessions/SKILL.md.

Session file format

Claude Code stores sessions as JSONL files in ~/.claude/projects/<encoded-path>/:

• Each line is a JSON record with a type field
• type: "user" — user message (message.content is a string) or tool result (message.content is a list with tool_result blocks)
• type: "assistant" — Claude response, message.content is a list of content blocks (text, thinking, tool_use)
• type: "custom-title" — session rename event with customTitle field
• Records include sessionId, timestamp, cwd, gitBranch

Environment variables

• CCS_SESSIONS_DIR — Override the sessions directory (default: ~/.claude/projects)

License

MIT