╭─╮╭──╮
 ╭╯ ╰╯   ╮
 ╰═══════╯
SKILL.md

/recall — Search Past Claude, Codex & Grok Sessions

Search all past Claude Code, Codex, and Grok sessions using full-text search with BM25 ranking.

Usage

python3 ~/.claude/skills/recall/scripts/recall.py [QUERY] [--project PATH] [--days N] [--source claude|codex|grok] [--limit N] [--reindex]

Examples

# Simple keyword search
python3 ~/.claude/skills/recall/scripts/recall.py "bufferStore"

# Phrase search (exact match)
python3 ~/.claude/skills/recall/scripts/recall.py '"ACP protocol"'

# Boolean query
python3 ~/.claude/skills/recall/scripts/recall.py "rust AND async"

# Prefix search
python3 ~/.claude/skills/recall/scripts/recall.py "buffer*"

# Filter by project and recency
python3 ~/.claude/skills/recall/scripts/recall.py "state machine" --project ~/my-project --days 7

# Search only Claude Code sessions
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source claude

# Search only Codex sessions
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source codex

# Search only Grok sessions
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source grok

# Force reindex
python3 ~/.claude/skills/recall/scripts/recall.py --reindex "test"

Query Syntax (FTS5)

  • Words: bufferStore — matches stemmed variants (e.g., "discussing" matches "discuss")
  • Phrases: "ACP protocol" — exact phrase match
  • Boolean: rust AND async, tauri OR electron, NOT deprecated
  • Prefix: buffer* — matches bufferStore, bufferMap, etc.
  • Combined: "state machine" AND test
  • Hyphens: claude-code is split into "claude" "code", since FTS5 reads a bare - as NOT. Quote the phrase to search it exactly.

After Finding a Match

To resume a session, cd into the project directory and use the appropriate command:

# Claude Code sessions [claude]
cd /path/to/project
claude --resume SESSION_ID

# Codex sessions [codex]
cd /path/to/project
codex resume SESSION_ID

# Grok sessions [grok]
cd /path/to/project
grok --resume SESSION_ID

Each result includes a File: path. Use it to read the raw transcript (auto-detects format):

python3 ~/.claude/skills/recall/scripts/read_session.py <File-path-from-result>

If results are missing File: paths, run --reindex to backfill.

Notes

  • Index is stored at ~/.recall.db (SQLite FTS5, auto-migrated from ~/.claude/recall.db), created readable only by you, with ~/.recall.db.lock serializing index updates across concurrent sessions
  • Indexes ~/.claude/projects/ (Claude Code), ~/.codex/sessions/ (Codex), and ~/.grok/sessions/**/chat_history.jsonl (Grok)
  • First run indexes all sessions; after that only the bytes a session has added are read, except for Grok, which rewrites its whole history file on every save
  • Omit the query to list recent sessions instead of searching
  • Run tests with python3 -m unittest discover tests -v from the skill root
  • Only user and assistant messages are indexed (tool calls, thinking blocks, state snapshots, synthetic harness context skipped)
  • Results show [claude], [codex], or [grok] tags to indicate the source