agsearch

Find the session you remember,
even when you don't remember its title.

Ranked full-text search across the coding-agent sessions already on your machine.
Claude Code and Codex CLI today, more next.

agsearch indexes the local transcripts your coding agents already write. Search them in one ranked list, preview the matching lines, and resume the original Claude Code or Codex session. Everything stays on your machine.

Quick start

brew install devcodes9/tap/agsearch
agsearch

Type anything you remember from a past conversation. Select a result to resume it.

Homebrew also installs fzf, which the interactive interface needs.

To run one search without installing anything:

uvx agsearch -n "stripe tax id"

Features

• Full-conversation search. Search user prompts and assistant replies, not only titles and session metadata.
• One list for both tools. Claude Code and Codex sessions appear together, labelled cc and cx. Adding another agent is a parser plus a source entry, with no change to search or ranking — Gemini CLI and opencode are the tracked candidates.
• Ranked results. BM25 ranking favors focused sessions and shows matching lines in context.
• Preview, read, or resume. Inspect a match, open the transcript in a pager, or return to the original session.
• Fully local. No uploads, API keys, hosted index, or network calls.
• Fast warm searches. A per-file cache reparses only transcripts that changed.

Installation

Homebrew

Recommended because it installs both agsearch and the fzf dependency:

brew install devcodes9/tap/agsearch

Python tool installers

uv tool install agsearch
# or
pipx install agsearch

The interactive interface needs fzf 0.35 or newer — that is the release which added the start event agsearch binds. Some distributions package an older one; fzf's own install script is the fallback. Without fzf, agsearch -n "query" still prints ranked matches.

Install script

curl -fsSL https://raw.githubusercontent.com/devcodes9/agsearch/main/install.sh | sh

This installs the latest release to ~/.local/bin. Set PREFIX to change the destination or AGSEARCH_VERSION to pin a release.

agsearch requires Python 3.9 or newer and has no Python package dependencies.

Usage

agsearch                       # browse all sessions in the interactive interface
agsearch "stripe tax id"       # open with an initial query
agsearch -n "stripe tax id"    # print ranked matches without fzf
agsearch --here "webhook"      # search only the current project
agsearch -p myapp "migration"  # search projects whose path contains "myapp"
agsearch --thinking "query"    # include assistant thinking blocks
agsearch --no-resume "query"   # print the selected resume command
agsearch --reindex             # rebuild the transcript cache
agsearch --version             # print the installed version

Interactive keys

Key	Action
Enter	Resume the selected session
Ctrl-O	Read the full conversation in your pager
Ctrl-Y	Copy the resume command
Ctrl-/	Toggle the preview pane

Selecting a result starts claude --resume or codex resume from the session's project directory. The current query is copied to the clipboard so you can find the same text after resuming.

For a global shortcut, see the hotkey guide.

Why not just /resume?

Claude Code's /resume picker and codex resume are good when you remember a session's title, branch, directory, or first prompt. They search metadata about the session.

agsearch searches the conversation itself. It also combines both tools in one list and includes Claude Code SDK and -p sessions that do not appear in the native picker.

Use the native picker when you remember what the session was called. Use agsearch when you remember what was said.

Search and ranking

agsearch drops common stopwords, applies conservative stemming, and ranks matching sessions with BM25 across three weighted fields: title and project, first prompt, and full transcript. Sessions covering more query terms rank first; relevance, recency, and previous resumes break close ties. Rare long typos fall back to subsequence matching, so conection pool still finds the session about connection pools.

Search is lexical, not semantic. It will not match concepts expressed with completely different words, and the first result is not guaranteed to be the session you intended.

Privacy and storage

agsearch reads:

• ~/.claude/projects/**/*.jsonl
• ~/.codex/sessions/**/*.jsonl

Its cache lives under ~/.cache/agsearch/. Transcript parsing and ranking happen locally, and only changed files are reparsed.

Important

Claude Code deletes transcripts after 30 days by default. To keep a longer searchable history, set cleanupPeriodDays in ~/.claude/settings.json:

{ "cleanupPeriodDays": 365 }

agsearch never changes this setting.

Session handling

• Claude Code subagent transcripts are folded into their resumable parent session.
• SDK and other automated sessions remain searchable but rank below user-started sessions.
• Sessions from deleted worktrees resume from the nearest existing parent directory.
• Recently active sessions are marked ● and require confirmation before reattaching.

Development

git clone https://github.com/devcodes9/agsearch.git
cd agsearch
python3 -m unittest discover -s tests

Changes to ranking should include a regression case in tests/. See the changelog and open issues.

License

MIT