home / skills / pchalasani / claude-code-tools / session-search

session-search skill

This skill helps you locate and summarize prior Claude Code or Codex-CLI sessions by querying and parsing JSONL session data.

npx playbooks add skill pchalasani/claude-code-tools --skill session-search

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.6 KB

---
name: session-search
description: For CLI agents WITHOUT subagent support (e.g., Codex CLI). Search previous code agent sessions for specific work, decisions, or code patterns.
---

> **If you are Claude Code:** Do NOT use this skill directly. Use the
> `session-searcher` subagent via the Task tool instead - it handles this more
> efficiently without polluting your context.

# session-search

Search and find previous code agent sessions (Claude-Code or Codex-CLI) for specific
work, decisions, or code patterns.

## Workflow

1. **Understand the query**: Identify what the user is looking for (code patterns,
   decisions, specific work, design direction)
2. **Search with aichat**: Run `aichat search --json -n 10 "[query]"` (use
   `-g "project"` to filter by project)
3. **Parse results**: Use `jq` to extract fields from JSONL output (session_id,
   project, created, snippet, file_path)
4. **Deep dive if needed**: Read session files at
   `~/.claude/projects/*/[session-id].jsonl` (max 3 files)
5. **Summarize**: Return a focused summary with key findings and references

Run `aichat search --help` to see all options (date filters, branch filters, etc.)
and JSONL field names.

## Output Format

Return a concise summary containing:

1. **Key Findings**: 2-3 bullet points answering the query
2. **Relevant Sessions**: Session IDs and dates for reference
3. **Specific Content**: Code snippets or quotes if directly relevant

Format as clean markdown, not raw JSON.

## Example

Query: "Find sessions where we discussed authentication design"

```bash
aichat search --json -n 10 "authentication design"
```

Summary:
- **Session abc123** (Dec 10): Discussed JWT vs session-based auth, decided on JWT
- **Session def456** (Dec 8): Implemented refresh token rotation pattern

## Constraints

- ALWAYS use `--json` flag with aichat search (otherwise it spawns interactive UI)
- NEVER return raw JSON output to the user - summarize and distill findings
- NEVER read more than 3 session files per query
- If no results found, suggest alternative search terms
- ONLY report information directly observed in files - never infer or extrapolate

## Error Handling

If `aichat search` command fails or is not found, ask user to install:

```bash
uv tool install claude-code-tools   # Python package
cargo install aichat-search         # Rust search TUI
```

Prerequisites:
- Node.js 16+ (for action menus)
- Rust/Cargo (for aichat-search)

If user doesn't have uv or cargo:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh           # uv
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh  # Rust
```

Overview

This skill helps CLI-based code agents search previous sessions for specific work, design decisions, or code patterns. It is tailored for environments without subagent support (e.g., Codex CLI) and returns concise, actionable summaries with references to matching session files. Use it to recover past reasoning, snippets, or decisions without loading large context into the current run.

How this skill works

The skill runs aichat search with --json to retrieve the top matching session entries, parses the JSONL output to extract session_id, project, created, snippet, and file_path, and optionally reads up to three session files for deeper context. It distills findings into key points, lists relevant sessions and dates, and includes exact snippets or quotes when directly observed. If the search tool fails or is missing, it provides clear install instructions and alternative commands.

When to use it

You need to find prior design decisions or rationale made in past agent sessions.
You want compact examples of code patterns previously used in the project.
You need citations (session IDs and dates) to justify a chosen approach.
You want to avoid re-running or re-deriving work that already exists in agent history.
You have limited context capacity and must surface a few targeted references.

Best practices

Always include precise search terms; add -g "project" to scope results to a project when possible.
Use the --json flag with aichat search to avoid interactive UI and enable parsing.
Limit deep file reads to three session files per query to avoid context bloat.
Report only facts observed in session files; do not infer intentions or outcomes beyond what is recorded.
If you are running Claude Code with subagent support, call the session-searcher subagent instead of this skill to prevent context pollution.

Example use cases

Locate earlier discussions comparing authentication strategies and extract the chosen pattern and rationale.
Find previous implementations of a specific utility function to reuse or adapt its code snippet.
Recover the session where a particular bug was diagnosed and capture the steps that reproduced it.
Gather references to prior architecture notes for a design review or PR justification.
Search for examples of how the agent handled error logging and monitoring configurations.

FAQ

What if aichat search is not installed or fails?

The skill will instruct you to install the required tools (uv and/or aichat-search) and provide the relevant install commands for Python (uv tool) and Rust (cargo).

Can the skill return raw JSON from search?

No. The tool always summarizes and distills results; it never returns raw JSON to the user.

How many session files will you read for context?

At most three session files per query, to keep the inspection focused and avoid overloading the current context.