Session History Search

/sessions (installed from EveryInc/compound-engineering-plugin ce-sessions)

Search session history across Claude Code, Codex, and Cursor and synthesize findings about what was worked on, tried, decided, or learned in prior sessions.

Usage

/ce-sessions [question or topic]
/ce-sessions

Pre-resolved context

Git branch (pre-resolved): !git rev-parse --abbrev-ref HEAD 2>/dev/null || true

If the line above resolved to a plain branch name (like feat/my-branch), use it for branch filtering and pass it to the synthesis subagent. If it still contains a backtick command string or is empty, derive the branch at runtime instead.

Repo name (pre-resolved): !basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || true

If the line above resolved to a plain repo folder name, use it for session discovery. Otherwise derive at runtime.

Note: 2026

The current year is 2026. Use this when interpreting session timestamps.

Guardrails

These rules apply at all times during orchestration and synthesis.

• Never read entire session files into context. Session files can be 1-7MB. Always use the extraction scripts to filter first, then reason over the filtered output.
• Never extract or reproduce tool call inputs/outputs verbatim. Summarize what was attempted and what happened.
• Never include thinking or reasoning block content. Claude Code thinking blocks are internal reasoning; Codex reasoning blocks are encrypted. Neither is actionable.
• Never analyze the current session. Its conversation history is already available to the caller.
• Surface technical content, not personal content. Sessions contain everything — credentials, frustration, half-formed opinions. Use judgment about what belongs in a technical summary and what doesn't.
• Fail fast on access errors. If session discovery fails on permissions, report the issue immediately. Do not retry the same operation with different tools or approaches — repeated retries waste tokens without changing the outcome.

Execution

If no question argument is provided, ask what the user wants to know about their session history. Use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini, ask_user in Pi (requires the pi-ask-user extension). Fall back to asking in plain text only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Step 1 — Determine scan window

Infer a time range from the user's question. Start narrow; widen only if a narrow scan finds nothing relevant.

Claude Code retains session history for ~30 days by default. Wider windows may find nothing on Claude Code unless the user has extended retention.

Step 2 — Discover sessions and extract metadata

Run the discovery + metadata pipeline (preserving the null-delimited xargs hardening that lets extract-metadata.py run in batch mode):

bash scripts/discover-sessions.sh <repo> <days> | tr '\n' '\0' | xargs -0 python3 scripts/extract-metadata.py --cwd-filter <repo>

Each output line is a JSON object describing a session (platform, file, size, ts, session, plus platform-specific fields). The final _meta line carries files_processed and parse_errors.

If the inventory's _meta line shows files_processed: 0, return "no relevant prior sessions" and stop.

If parse_errors > 0, note that some sessions could not be parsed and proceed with what was returned.

To narrow the platform set, add --platform claude, --platform codex, or --platform cursor to the discover-sessions.sh invocation. Default to all three.

Step 3 — Filter and rank

Apply these filters in order to pick the sessions worth deep-diving:

1. Branch filter (Claude Code only). Keep sessions where branch == dispatch_branch exactly, or where the branch name contains a keyword from the question's topic (e.g., a question about "auth middleware" matches branches feat/auth-fix, chore/auth-refactor). Codex sessions don't carry gitBranch — skip this filter for them.

2. If the branch filter returned zero sessions, or you're processing Codex sessions:

   • Derive 2-4 keywords from the question's topic. For "a recent crash in the auth middleware where session-validation rejects valid tokens", derive auth,middleware,session,token (or similar).
   • Re-invoke the discovery pipeline with --keyword K1,K2,... appended to the extract-metadata.py invocation. The script returns sessions with non-zero match_count plus per-keyword counts.
   • If files_matched: 0, return "no relevant prior sessions" and stop. Do not extract anything.
   • If files_matched > 0, treat those sessions as candidates. Rank by match_count, break ties by per-keyword counts.

3. Drop sessions outside the scan window. Use last_ts when available, fall back to ts. Discard sessions where both fall before the window start.

4. Exclude the current session — its conversation history is already available to the caller.

5. Apply the deep-dive cap. Take at most 5 sessions total across all platforms. Narrow by branch-match → match_count → file size > 30KB → recency.

6. Proceed only if at least one session remains after filtering. Otherwise return "no relevant prior sessions" and stop.

Note: gitBranch is captured at the first user message only. A session that began on main and did substantive work on a feature branch via mid-session git checkout records branch: "main". Branch-match returning nothing is not conclusive evidence — that's why the keyword-filter fallback in step 2 is required.

Step 4 — Set up scratch space

Create a per-run throwaway scratch directory:

SCRATCH=$(mktemp -d -t ce-sessions-XXXXXX)

Capture the absolute path; thread it into Step 5 and Step 6. The OS handles cleanup on session end; an explicit rm -rf "$SCRATCH" at the end of Step 7 is harmless and makes intent explicit.