Changelog¶

Responsive detail pane in the TUI (#51)¶

The record-detail pane now adapts to the terminal width. Wide terminals keep it on the right beside the results; narrow terminals (under ~100 columns) stack it below the results and leave it closed until you select a row, so small screens get a full-height result list and the detail opens on demand — the same shape tig uses for its diff view. Resizing across the threshold moves the pane live.

Calm search progress in the TUI (#50)¶

While a search runs, the results statusline now shows a star spinner, a live elapsed clock, a progress bar over the sources scanned, and the running match count — replacing the stream of per-source scanning text that previously redrew on every file. When the search ends, the bar stays on as the outcome: full and green when complete, frozen in gray where a cancelled search stopped.

The verbose counts are one keystroke away: ctrl+\ toggles a detail row beneath the statusline carrying the scanning detail while the search runs and the full summary — matches, sources, elapsed — once it ends, and the toggle stays on for the rest of the session. On narrow terminals the statusline keeps the essentials: the progress percent, the match count, and a green “Done” or gray “Stopped” after the search finishes.

Faster searches on large histories (#46)¶

Searches now skip lines that cannot match before parsing them, and searches with a result limit read supported history files newest-first and stop as soon as enough matches are found, instead of scanning whole files. Results are the same as before — searches just finish sooner.

The MCP server and TUI reuse earlier search work (#46)¶

Long-running sessions now remember what each history file contained and reuse it when the file has not changed since, so repeating or refining a search no longer re-reads everything from disk.

OR queries return every matching record (#46)¶

Search queries combining terms with OR — like (deploy OR release) — previously required all branches to appear at once, so records matching only one branch were silently dropped. Negated terms had the same problem and could match nothing at all. Boolean queries now follow their written meaning.

Searching a project’s folder name finds its conversations (#46)¶

Searches whose term appears in a conversation’s file path — most often a project directory name — could come back empty because a fast content-only pre-scan dropped those files before they were read. Path matches are now always followed up.

Cursor IDE workspace history reliably appears in broad searches (#46)¶

Broad searches could skip Cursor IDE workspace databases during a fast pre-scan — the same way the main history database used to go missing. Workspace databases are now always handed to the proper reader.

Architecture records for the search engine (#46)¶

Three new architecture decision records document how searches are planned and executed, and the ground rules for any future native-code acceleration. Profiling and benchmark reports now also show which scan strategy each source used.

Huge Cursor IDE databases no longer slow every search (#45)¶

Searching Cursor IDE history now reads only the chat and prompt entries from state.vscdb instead of loading the whole database. On multi-gigabyte databases — common after heavy Cursor use — searches previously pulled gigabytes of unrelated editor data through memory just to throw it away.

Cursor IDE search results no longer go missing (#44)¶

Searches now reliably find matches stored in Cursor IDE’s history database. Previously, a fast pre-scan could mistake the database for an ordinary text file and skip it, silently leaving Cursor IDE matches out of search results.

New script: scripts/profile_engine.py (#44)¶

See where search time goes. Profile prompt search, conversation search, grep-style search, or source discovery — one component or the whole matrix — and get a readable terminal summary. Add --json or --ndjson to save a shareable, privacy-safe report: timings only, never prompt text or local paths. Dev-only; not shipped in the wheel.

scripts/benchmark.py: profiler benchmarks built in (#44)¶

Run the profiler suite with --commands profile-engine, or just the Cursor IDE set with profile-engine-cursor-ide. Benchmark results now carry the matching profile data, and --top-spans shows the slowest steps right in the terminal. Asking for zero benchmarks by mistake is now an error instead of an empty report.

New subcommand: benchmark.py analyze (#44)¶

Turn a saved benchmark file into a bottleneck report — slowest commands, slowest steps, and warnings — without rerunning anything.

Faster scoped discovery planning (#41)¶

Search, grep, find, and MCP lookup paths avoid metadata-rich source inventory when they only need parseable handles. Prompt and conversation scopes also narrow catalogue roles before filesystem walks, and committed benchmark entries now make their --max-count and --limit caps explicit.

Search scope vocabulary (#38)¶

Bare CLI and MCP searches now run in prompts scope. Dedicated prompt-history stores are included in that default, and transcript-only backends still project user turns into prompt scope when an app does not keep a separate prompt log.

Full conversation, session, assistant, tool, and event records require --scope conversations, scope="conversations", or scope:conversations. Use all to search prompts and conversations together.

OpenCode backend (#30)¶

agentgrep now searches OpenCode (formerly sst/opencode). OpenCode keeps conversations in a single SQLite database (opencode.db) under ~/.local/share/opencode, so it joins the relational session → message → part tables and surfaces each text-bearing part — user prompts, assistant replies, model reasoning, and subtask prompts — with the session title, working directory, and model attached. Discovery honours XDG_DATA_HOME and the OPENCODE_DB override, and every other on-disk store (the legacy JSON layout, config, snapshots, the repo cache, logs, and tool output) is catalogued for completeness, with auth.json documented but never indexed. See OpenCode for details.

Pi backend (#28)¶

agentgrep now searches Pi (the earendil-works “Pi Agent Harness”) as a new backend. Pi keeps each conversation as one append-only JSONL session file under ~/.pi/agent/sessions/, grouped by working directory, with no separate prompt-history log or SQLite index — so user prompts surface as prompts and assistant and tool turns as history straight from the transcript. Discovery honours PI_CODING_AGENT_DIR and the flat PI_CODING_AGENT_SESSION_DIR override (where the working directory is recovered from the session header), and every other on-disk pi store — settings, models, themes, tools, managed binaries, prompt templates, the debug log, and the npm extension root — is catalogued for completeness, with auth.json documented but never indexed. See Pi for details.

Cursor split into cursor-cli and cursor-ide (#27)¶

The single cursor backend is gone. Cursor is two separate applications with disjoint data homes and on-disk formats — the cursor-agent terminal CLI and the desktop IDE — so agentgrep now models them as two agents, cursor-cli and cursor-ide. Anywhere you referenced cursor (the --agent flag, agent: query predicates, the agentgrep://sources/{agent} MCP resource, record agent fields), pick the surface you mean.

Before:

$ agentgrep search foo --agent cursor

After — the terminal agent:

$ agentgrep search foo --agent cursor-cli

After — the desktop app:

$ agentgrep search foo --agent cursor-ide

Store and adapter identifiers lost their now-redundant infix to match the agent (cursor.cli.transcripts → cursor-cli.transcripts, cursor.state_vscdb_modern.v1 → cursor_ide.state_vscdb_modern.v1). See Cursor CLI and Cursor IDE.

Cursor CLI prompt history (#27)¶

Cursor CLI now has a prompt-history store, parity with the Claude, Codex, and Grok backends. agentgrep reads the typed-prompt recall buffer from ~/.config/cursor/prompt_history.json — a directory the catalogue never knew, because Cursor moved its CLI home to the lowercase ~/.config/cursor/ while the catalogue only watched ~/.cursor/. Searching --agent cursor-cli now returns what you typed into cursor-agent, not just the full transcripts.

Cursor IDE per-workspace history (#27)¶

The Cursor IDE backend now reads per-workspace databases at workspaceStorage/<hash>/state.vscdb, not just the global store. Both surface the aiService.prompts typed-prompt history, which previous builds advertised but did not actually extract — prompt entries carry no role field, so the generic walker skipped them.

Best-effort Cursor CLI chat parser (#27)¶

Cursor CLI’s newer chat backend stores each session as content-addressed protobuf blobs in a chats/<hash>/<uuid>/store.db SQLite database, with no published schema. agentgrep can open these on a best-effort basis: a schema-less protobuf wire-walker surfaces the readable text it finds. The store is inspectable (opt-in) rather than searched by default, since the extraction is noisier than and overlaps the cleaner transcripts.

Removed: regex, OR, and files-without-match search modes¶

Three search modes that bypassed the ripgrep prefilter—triggering a full-corpus scan with high peak memory usage—have been removed until they can be implemented with bounded memory. This affects the CLI search --regex and search --any flags, the regex and any_term parameters in the MCP search and validate_query tools, and grep -L (--files-without-match).

agentgrep search is now restricted to literal AND-matching to ensure performance and stability. grep and find remain regex-by-default as they utilize ripgrep directly. Re-introducing the removed modes with bounded memory is tracked in #32.

Removed: the fuzzy subcommand¶

agentgrep fuzzy — a fzf --filter-shaped filter over stdin that never read the agent stores — has been removed. It sat outside agentgrep’s prompt/history search scope and only approximated fzf, scoring with rapidfuzz rather than fzf’s own algorithm.

Before:

$ agentgrep grep foo | agentgrep fuzzy bar

After — pipe through fzf directly:

$ agentgrep grep foo | fzf --filter bar

Re-adding it with a faithful fzf port is tracked in #34.

Source version detection strategies (#25)¶

agentgrep now reports how each discovered source version was detected. Source discovery and MCP list_sources payloads include app-version context, data-shape version, strategy, confidence, and concise evidence, while search result records stay focused on prompt/history content.

Codex history detection now distinguishes modern history.jsonl records (session_id, ts, text) from legacy history.json records (command, timestamp) even when both coexist under a modern Codex config root. Claude Code detection uses prompt-history shape and embedded transcript version metadata when available.

Grok CLI backend (#24)¶

Grok CLI joins Codex, Claude Code, Cursor, and Gemini as a first-class backend. Three adapters parse the on-disk stores under ~/.grok/sessions/: per-project prompt_history.jsonl (user-prompt audit log), per-session chat_history.jsonl (full transcripts with system, user, assistant, tool_use, and tool_result records), and the global session_search.sqlite FTS5 index. Discovery honours the GROK_HOME environment variable. Seven additional stores are catalogued as documentary-only for future adapter work.

Backend documentation pages (#24)¶

A new Backends section provides a support matrix and per-engine pages (Codex, Claude Code, Cursor CLI, Cursor IDE, Gemini CLI, Grok CLI) documenting store layouts, adapter IDs, and record schemas.

search: Relevance-ranked results with session grouping (#20)¶

search now scores results by rapidfuzz relevance, sorts best-first, and groups by session. Progress spinner with Enter-to-answer-now during collection. Pretty snippet-first output with amber highlights. Flags: --threshold, --no-rank, --no-group.

New flag: --style=pretty for grep (#18)¶

Snippet-first output with warm-amber match highlights and a dim provenance line underneath. Relative timestamps (“3d ago”) replace ISO strings. Use --style=default (or omit) for the existing rg-faithful output.

Bare agentgrep <terms> no longer auto-runs search¶

Spell the subcommand out: agentgrep search bliss. Bare agentgrep (no args) now prints a directory of subcommands.

find <PATTERN> is regex by default¶

fd parity. Use -F for literal substring.

New subcommand: grep¶

rg/ag-shaped content search. Flags: --json / --ndjson / --vimgrep / --column / -c / -l / -L / -o / -n / -F / -E / -w. grep-faithful exit codes.

New subcommand: fuzzy¶

fzf --filter-shaped non-interactive ranking over stdin. Extended-search syntax, --algo / --tiebreak, and field-scoped --delimiter / --nth / --with-nth.

fd-shaped find flags¶

-g / -F / --exact, -t / --type, -e / --extension, -l / --list-details, -0 / --print0, --full-path. One path per line by default; -g matches basename.

Query language across search / grep / find¶

Field predicates (agent:, path:, mtime:, timestamp:, model:, role:, type:, store:, adapter_id:, text:), AND / OR / NOT with parens, comparison + range operators, ISO and relative date literals. Source-layer fields prune before file I/O.

--ui overlay on every subcommand¶

Opens the Textual explorer pre-filled with the same query; the explorer accepts the query language on re-search too. The TUI moves behind the explicit agentgrep ui subcommand.

--no-progress everywhere¶

Alias for --progress=never on every subcommand; find also gains the full --progress {auto,always,never} selector.

Headless event-stream engine¶

iter_search_events and iter_find_events yield typed pydantic events. CLI text + NDJSON output is live-streaming.

scripts/benchmark.py (#9)¶

Cross-commit hyperfine benchmark harness for catching performance regressions on a branch. Dev-only; not shipped in the wheel. See Benchmark harness for invocation recipes.

• Source split: argparse into agentgrep.cli.parser, output rendering into agentgrep.cli.render. Re-exports preserved.

CLI reference site¶

The new /cli/ section opens with a tabbed installer, a card grid linking to agentgrep search and agentgrep find, and an “Use from another agent” callout describing the --json / --ndjson contract for non-MCP consumers. Each subcommand page renders its option list from the live argparse tree via gp-sphinx’s sphinx-autodoc-argparse extension, then documents the JSON record shape with cross-references to SearchRecord and FindRecord.

CLI install widget¶

A new {cli-install} Sphinx directive renders one row of install- method tabs (uvx run / pipx run / uv add / pip install) and, for each method, a panel pairing the install command with a runnable CLI usage snippet. The widget mirrors the existing {library-install} and {mcp-install} widgets — same prehydrate- driven first-paint behavior, same localStorage persistence across pages — so the homepage now carries three sibling installers, one per consumption surface.

CLI cooldowns¶

The {cli-install} widget grows the same “Configure cooldowns” picker the MCP installer has carried since 0.1.0a3. Each method panel now exists in three variants (off / days / bypass) so a security-conscious terminal user can drive uvx’s --exclude-newer, pipx’s --uploaded-prior-to, or uv add / pip install’s cooldown equivalents straight from the docs site. Toggling cooldowns or changing the day count live-updates every duration / date sentinel in the visible snippet, the settings sub-view exposes a bypass radio for uv-backed installs, and saved state survives gp-sphinx SPA nav and is shared with any other {cli-install} widget on the page.

uv-flavored days-mode snippets include --exclude-newer-package agentgrep=2099-01-01 so the global cooldown applies to transitive deps without filtering agentgrep itself out of the resolver (a fresh release of agentgrep would otherwise be newer than the cutoff). pip has no per-package cutoff override, so the pipx and pip days panels carry a note pointing users at the uv-flavored snippets when the cooldown filters out a recent agentgrep release.

Default to the Textual explorer (#7)¶

Bare agentgrep now launches the interactive Textual explorer (equivalent to agentgrep ui); agentgrep <terms> remains shorthand for agentgrep search <terms>. The new ui subcommand accepts an optional initial-query argument, so agentgrep ui bliss seeds the search bar without leaving the explorer to run a one-shot CLI query.

Live, cancellable search and sticky in-list filter (#7)¶

The explorer’s top input dispatches a backend search on Enter and signals any in-flight worker to wrap up before the next one starts, so re-querying mid-stream no longer piles up cancellations. A separate filter input below the results narrows what’s already loaded on every keystroke without re-running the search. Plain up returns focus from the filter to the search bar; plain right on an empty filter releases focus to the detail pane, so the full arrow-key perimeter walks the three columns without reaching for Ctrl-L.

Per-pane chrome with scroll indicators and tig-style timestamps (#7)¶

The results and detail panes each carry a one-line footer that mirrors tig’s chrome conventions. The results footer shows match count, cursor position, and a scroll percent that reads 100% when the view fits; the detail footer shows the compact source path and the same scroll percent. Result-row timestamps render in the viewer’s local timezone with offset (YYYY-MM-DD HH:MM ±HHMM) rather than the raw upstream ISO string clipped to 20 characters.

Filter and detail responsiveness on large result sets (#7)¶

Filter passes no longer recompute build_search_haystack().casefold() for every record on every keystroke — the casefolded haystack is memoized for the lifetime of one search. The filter applies adds/removes as deltas to the result list rather than rebuilding from scratch, the streaming batch-apply yields to the event loop between chunks so the UI stays interactive while a worker streams thousands of matches in, and the detail pane memoizes body formatting and the first-match line so re-visiting a record skips both Rich render passes.

MCP install widget ships working cooldown snippets¶

The mcp-install widget’s days-mode snippets now resolve for fresh agentgrep releases. The 0.1.0a3 shape emitted uvx --exclude-newer <DURATION> --from agentgrep agentgrep-mcp without a per-package override, so a cooldown shorter than agentgrep’s most-recent-release age made the install unresolvable (uv emits no versions of agentgrep).

uvx days panels now carry --exclude-newer-package agentgrep=2099-01-01 so the cooldown stays applied to transitive deps without filtering agentgrep itself out of the resolver.

pipx and pip days/bypass panels fall back to the bare install command. Verified against pip 26.1.1 source at /_internal/cli/cmdoptions.py:463: --uploaded-prior-to is a single global cutoff with no per-package override flag (pip issue #13674 landed a relative-duration parser, but no per-package issue is open). pipx’s commands/run_uv.py only translates a narrow whitelist of pip args to its uv backend and does not include --exclude-newer, so the uv backend path can’t carry the cooldown either. The fallback ships a working command; the per-panel cooldown note redirects readers to the uvx tab when they need true cooldown enforcement.

agentgrep.ui subpackage (#7)¶

The streaming Textual app moves out of agentgrep.__init__ into a dedicated agentgrep.ui subpackage. run_ui() and build_streaming_ui_app() live in agentgrep.ui.app with Textual deferred to importlib.import_module at factory-call time — bare import agentgrep does not pull Textual.

Eight new MCP tools¶

The MCP server gains list_stores, get_store_descriptor, inspect_record_sample, list_sources, filter_sources, summarize_discovery, recent_sessions, and validate_query. Together they let MCP clients introspect the canonical store catalog (role, format, upstream schema notes), filter discovered sources by path-kind and source-kind, summarize what’s discoverable per agent, fetch a small sample of parsed records from one adapter+path, narrow recent activity by mtime window, and dry-run a regex against sample text before issuing a broad cross-agent search.

Three new MCP resources¶

agentgrep://catalog returns the full StoreCatalog Pydantic payload (every store agentgrep knows about — including ones that aren’t searched by default — with role, format, upstream reference, and schema notes). agentgrep://store-roles and agentgrep://store-formats enumerate the supporting enum values with one-line descriptions so an agent can build prompts or summaries without scraping the docs site.

MCP server hardening¶

The MCP server now runs through FastMCP’s timing, response-size, and error-handling middleware plus an agentgrep-flavored audit log that records agentgrep_tool / agentgrep_outcome / agentgrep_duration_ms / agentgrep_args_summary on every call. Sensitive argument payloads (terms, pattern, sample_text) are redacted to {len, sha256_prefix} before logging so the audit stream stays operator-debuggable without leaking the caller’s prompts. The server instructions are now composed from named segments (HEADER / SCOPE / SEARCH_VS_DISCOVERY / DEFAULTS / RESOURCES / PRIVACY) so future agent-context segments slot in without rewriting the base set.

MCP install widget¶

The MCP landing page hosts a tabbed installer that picks the right snippet across Claude Code, Claude Desktop, Codex, Gemini, and Cursor, three install methods (uvx / pipx / pip), each client’s relevant config scopes, and an optional dependency cooldown (off / N-day cooldown / bypass-global). The widget remembers your selections across pages so the same snippet stays visible while you browse the docs.

Library install + quickstart widget¶

The library landing page hosts a sibling widget with one row of install-method tabs (uvx run, pipx run, uv add, pip install) and a runnable Python quickstart on every panel — install command on top, end-to-end search snippet below. The quickstart calls run_search_query() directly so readers see the same shape the CLI uses.

Sidebar: Library and MCP first-class¶

The Packages group is gone. The left sidebar now lists Get started, Library, MCP, Reference, and Project as siblings, with Library and MCP carrying the install widgets. Old /packages/agentgrep/* URLs redirect to /library/*.

scripts/mcp_swap.py¶

A new dev-only script swaps the MCP server entry in every installed agent CLI (Claude, Codex, Cursor, Gemini) between a pinned release and the local checkout. just mcp-detect lists which CLIs are present, just mcp-status shows the current entry, just mcp-use-local rewrites configs to run uv --directory <repo> run agentgrep-mcp, and just mcp-revert restores from a timestamped backup. State and backups live in $XDG_STATE_HOME/agentgrep-dev/swap/ so the script never edits the same file twice without a recoverable undo path.

MCP server refactor¶

src/agentgrep/mcp.py is now a mcp/ subpackage with per-domain tool modules (search_tools, discovery_tools, catalog_tools, diagnostic_tools) plus separate models.py, resources.py, prompts.py, instructions.py, and middleware.py. The entry point agentgrep-mcp = "agentgrep.mcp:main" is preserved through __init__.py re-exports.

Top-level README¶

The project ships a top-level README.md for GitHub and PyPI, with the project pitch, a single-client install snippet, the library quickstart, and links to docs / source / issues.

Gemini CLI search support (#4)¶

A new --agent gemini selector searches Google Gemini CLI sessions at ${GEMINI_CLI_HOME or ${HOME}/.gemini}/tmp/<project_hash>/chats/session-*.jsonl, the pre-Feb 2026 single-file .json sessions upstream still reads, and the per-project logs.json prompt audit log. The chat parser handles Gemini’s mixed-record JSONL — session metadata lines, user and gemini message records, and {"$set": …} metadata updates — surfaces user prompts and assistant content, and pulls searchable text from thoughts[*] and toolCalls[*] when an assistant turn’s content is empty. The logs parser walks the flat LogEntry array as a prompt-history store. The helper gemini_project_hash() reproduces Gemini CLI’s sha256(absolute_path) derivation so consumers can map a working directory to its tmp shard.

The CODEX_HOME and GEMINI_CLI_HOME environment overrides are honoured at discovery time; a non-existent path emits a logging.WARNING (via agentgrep’s module logger, structured with agentgrep_env_var / agentgrep_env_path extra= fields) and falls back to the default home root.

Cursor CLI agent search support (#4)¶

--agent cursor now searches the Cursor CLI agent’s per-project transcripts at ${HOME}/.cursor/projects/<id>/agent-transcripts/<session_uuid>/<session_uuid>.jsonl in addition to the existing Cursor IDE state store. Cursor transcripts carry no native timestamp; agentgrep backfills the file’s mtime as a session-level timestamp. Sibling project files (repo.json, mcp-approvals.json, terminals/, canvases/) are explicitly excluded from search so transcripts stay the focus.

Storage catalogue (#4)¶

A new agentgrep.stores module exposes StoreDescriptor and StoreCatalog — frozen Pydantic models describing one on-disk location per row with role, format, path pattern, observed_version, observed_at, and a pointer to the upstream type definition where one is public. agentgrep.store_catalog.CATALOG ships an initial registry covering Claude Code, Cursor (IDE and CLI agent kept distinct), Codex, and Gemini CLI. Each runtime-discovered row carries a DiscoverySpec that drives :func:~agentgrep.discover_sources directly, so future upstream schema renames become a one-row edit. Rows whose backing files upstream does not write — Gemini’s would-be history/ archive and the Antigravity protobuf files (Antigravity is a separate Google IDE product, not Gemini CLI) — are not declared.

Search beneath dotfile .gitignore (#4)¶

agentgrep search no longer reports “No matches found.” when ~/.claude, ~/.codex, or ~/.cursor lives inside a dotfile-managed tree (yadm, chezmoi, stow, bare-git, mr). The underlying fd and rg invocations now bypass .gitignore and .fdignore semantics so agent stores under $HOME are always discovered.

New storage-catalog reference page (#4)¶

A new Storage catalogue page walks through the per-agent storage layouts, names the upstream-pinned schemas where they exist, and explains how to add or update a descriptor.

Live-streaming --ui mode (#2)¶

agentgrep search <query> --ui no longer blocks on the search before opening the UI. The Textual app mounts up front, the search runs in a background worker, and records stream into the results list as they’re discovered. A filter input on top of the results list debounces typing and runs the substring filter on a worker thread, so typing stays instant regardless of how many records are loaded. The chrome above the filter shows the same spinner / scanning-N/M-sources / matches / elapsed line the CLI spinner uses, themed for the dark-terminal palette.

The detail pane on the right is format-aware: JSON bodies render through Rich’s syntax highlighter with the line containing the first search-term match emphasized, Markdown bodies render through Rich’s Markdown renderable (headings, fenced code blocks, lists), and plain-text bodies keep the bold-yellow match highlighting from the CLI output. When the first match is deep inside a body the pane opens centered on it instead of at the top.

Navigation borrows from vim and less. j / k move the cursor in the results list and scroll the detail pane; g / G jump top / bottom; Ctrl-D / Ctrl-U half-page; Ctrl-F / Ctrl-B full-page in the detail pane; Ctrl-hjkl switch focus between the filter input, the results list, and the detail pane tmux-style (Backspace aliases Ctrl-H for terminals that fold the two). q quits, Esc cancels an in-flight search, and Ctrl-C cancels the search on first press then quits on the next. Running --ui without query terms doubles as an interactive browse-everything mode.