Changelog¶

mcp_swap.py swaps opencode and pi¶

The dev config-swap helper now writes two more agent CLIs: $XDG_CONFIG_HOME/opencode/opencode.jsonc (container key mcp, argv packed into one command array, environment spelled environment) and ~/.pi/agent/mcp.json, which is read by the third-party pi-mcp-adapter rather than by pi itself — detect says so rather than reporting a swap that cannot take effect. Both files are JSONC, so the swap edits them through a splicing codec that rewrites only the members that differ: comments, trailing commas, indent width, and the absence of a final newline all survive. Per-CLI container keys and entry dialects are now data on CLIInfo instead of a branch per CLI in each of the four read/write/delete/enumerate functions.

mcp_swap.py use-local --pr and safer writes¶

use-local --pr N points every CLI at a pull request’s head (uvx --from git+<remote>@refs/pull/N/head <entry>) instead of the working copy. Nothing is checked out, so revert needs no cleanup, and the ref lives on the base repo, so fork pull requests work unchanged. Before anything is written the spec is launched once for an MCP initialize round trip, so an unresolvable ref fails there rather than inside every agent; --no-preflight skips the probe. Writes are safer in four ways: a symlinked config is updated through the link with its permission bits intact instead of being replaced by a regular file, backups are created with O_EXCL so one can never clobber another, re-swapping a layer keeps the original pre-swap backup rather than recording the already-swapped config, and the recovery record is persisted before the config changes so a failed write stays revertible.

Every store an agent keeps is now catalogued¶

The catalogue used to list the stores agentgrep searches. It now also carries the ones it deliberately does not — app state, derived caches, and stores whose contents are encrypted — so find and the MCP store tools describe an agent’s real on-disk surface instead of only the searchable slice of it. Each row says which kind of store it is and why it is or is not searched. See Kinds of storage an agent keeps. (#161)

Backend pages document the whole storage surface¶

Each backend page now describes every kind of store that agent keeps and where it keeps it — including how it stores git worktrees — rather than only the paths agentgrep reads. See Backends and Worktrees, and why a repo’s history splits. (#161)

Recorded store observations¶

scripts/observe_stores.py records the shape of each agent’s stores — key names, table and column names, counts, never values — as a per-version TOML manifest, and observe check reports what has drifted since. The catalogue pages render the recorded shapes, so a documented claim traces back to a version it was observed against, and a store that changes upstream is caught rather than quietly misdescribed. See Observed record shapes. (#161)

Control search depth with depth:/effort:¶

depth:targeted, depth:exhaustive, and the effort: alias now work as typed search text, the same way scope:all already does, instead of requiring --deep/--exhaustive flags or the MCP effort= parameter. Conflicting or malformed combinations (depth:targeted effort:exhaustive, a depth: term under NOT) are rejected before a search runs. In the TUI, the depth-offer panel now shows and types the matching depth: term when clicked, so the syntax is discoverable without leaving the keyboard. See Query language for details. (#158)

Ctrl-C now stops a slow exhaustive search¶

Previously, cancelling an exhaustive-effort search (--exhaustive, /exhaustive, or the new depth:exhaustive) could leave the TUI stuck while one especially large or slow store was still being read — sometimes for over a minute, with no way to interrupt it. Ctrl-C now stops the search immediately, whether it’s still discovering which stores to search or already reading one. (#158)

Filter by record kind with kind:prompt / kind:history¶

kind is now a registered, queryable field — kind:prompt and kind:history filter the same way across the CLI, the MCP search tool, and the TUI search box. (#156)

See where you’re reading in the detail pane¶

The right-hand detail pane previously showed a position indicator only during an active visual selection (tmux-style v). It now paints an ambient current-line marker whenever the pane holds focus, so you always know where you are. (#157)

A typo’d query field no longer fails silently¶

Searching agnet:codex or any other unregistered field:value predicate used to run a zero-signal literal search with no explanation. The CLI, MCP, and TUI search box now surface a warning — with a “did you mean” suggestion when one is close — while the literal search still runs, so a plain colon in ordinary text (a URL, a Windows path) stays silent. (#156)

The idle screen’s search-depth block and completion dropdown no longer trap navigation¶

Clicking “Deep search” or “Search all conversations” grabbed the mouse with no way out, arrow keys inside the same block cycled forever with no keyboard escape, and the completion dropdown that suggests field values stayed open indefinitely once focus moved elsewhere. All three now release focus normally. (#157)

The search-depth block’s instructions are legible again¶

The lead sentence rendered at a flat, often near-invisible “dim” contrast; it now resolves the same calibrated color used for de-emphasized text elsewhere in the UI. (#157)

Copy the explorer’s selection with Ctrl-C (#155)¶

Select text in the Textual explorer with the mouse and press Ctrl-C to copy it. Cmd-C does the same, as do Ctrl-Shift-C and Cmd-Shift-C in terminals that forward them rather than claiming them. With nothing selected, Ctrl-C keeps its existing job — stop the running search, then quit — so one key covers both without a mode to remember.

The detail pane’s own verbs are unchanged: y copies the raw source, Y the rendered text, and v starts a tmux-style visual selection you yank with y. See Copying for details.

A copy no longer reports success it cannot observe (#155)¶

agentgrep hands text to the terminal with an OSC 52 escape, which nothing acknowledges — yet the explorer said “copied source” either way. Inside tmux that claim was usually false, because tmux discards the sequence unless set -g set-clipboard on is configured, and macOS Terminal ignores it outright. The notification now reports what was sent rather than that it arrived, and names the tmux setting once per session when you are running inside one.

Copying returns what you selected (#155)¶

Selecting a record shown as JSON and copying it replaced the clipboard with an empty string, discarding whatever you had there. A selection also outlived the record it was made in, so copying after moving to another result returned text from a record you never highlighted. Both now behave as the highlight suggests.

Ctrl-C in a search box copies instead of erasing the query (#155)¶

Selecting part of a query and pressing Ctrl-C deleted the whole query and copied nothing, with no way to undo it. Ctrl-C now copies the selection when there is one, in the search bar, the in-list filter, and the Ctrl-R history modal, and still clears the box when there is not.

Ask agentgrep which version it is running (#154)¶

agentgrep --version prints the released version, and agentgrep.__version__ exposes it to a library consumer. Run from a git checkout, both also name the commit, so a development build a few commits past a release identifies itself rather than reporting a release number that is no longer true of it.

The explorer reports its build with /status (#154)¶

/status, aliased /version, shows the version, whether this is a release or a development build, and the git ref — so a bug filed from inside the explorer can say exactly what was running. See TUI for details.

The explorer shows results while a wide search is still running (#151)¶

A scope:all search in the Textual explorer showed an empty canvas until the whole scan finished. Results now stream in as each source is read, newest-first. A search run under an explicit result limit is unchanged.

The search progress line stays inside its terminal (#151)¶

A query or filename with wide characters drew a progress line wider than the terminal, stranding a row of scrollback on each redraw. The line now measures itself as the terminal does, and abbreviates its interrupt reminder rather than dropping it in a narrow pane.

A long search acknowledges the key you pressed (#151)¶

Pressing Enter during a wide search set the request immediately but left the progress line reading “scanning” for seconds. The line now confirms the keypress on the next frame, and offers Ctrl-C instead while the search is still finding files, where answering early has nothing to return.

The stacked explorer favors the detail pane¶

A terminal too narrow for side-by-side panes stacks the results list over the detail pane. The detail pane now takes the larger share of that split, so the record you selected is the one with room to be read, and the list above keeps enough rows to show its neighbours. Both panes hold a four-row floor, so a short terminal compresses the split rather than losing a pane. The side-by-side layout is unchanged.

MCP search cursors are removed (#143)¶

MCP search returns one ordered response capped by limit, with no continuation cursor. The agcur1 search cursors shipped in agentgrep 0.1.0a22 are no longer accepted — rerun without cursor, then refine the query or raise limit. MCP find pagination is unchanged.

Transcript-only agents leave the default search (#143)¶

Cursor IDE, OpenCode, and Pi expose prompts only through their chat transcripts, so they no longer contribute to a default search, grep, or ui request. Reach them with --exhaustive, or with --scope conversations or --scope all.

Search events and the MCP response carry run outcomes (#143)¶

SourceFinished and SearchFinished gained required fields, and the MCP search response now reports effort, outcome, coverage, and suggested next actions. Library consumers that construct or re-validate these events must supply the new fields.

Choose how deep a search reads (#143)¶

search and grep read fast prompt history by default. --deep adds a bounded set of conversations selected from matching prompt evidence, and --exhaustive reads every eligible conversation backend. MCP search and the Textual explorer offer the same three levels. See agentgrep search for details.

Reach a deeper search from inside the explorer (#143)¶

The idle canvas lists the depth choices the engine offers for the query you have typed, selectable by mouse or keyboard, so reaching conversations no longer costs a shallow search first. /deep and /exhaustive also work with no prior search, and /deep 50 bounds one request. See Finding the depth ladder.

Results say how complete they are (#143)¶

Every search reports whether its answer is exact, bounded, or approximate, which sources it covered, and what to run next to widen it. An empty result names the surface it actually read, so a shallow miss reads as one rung’s miss rather than an empty corpus.

--limit no longer discards the best results (#113)¶

A capped search stopped reading once it had seen enough records in scan order, so the newest or highest-scoring matches could be cut before ranking ever ran. Ordered requests now consider the full candidate set before applying the cap.

A replaced search stops promptly in the explorer (#143)¶

Starting a search while one was still running could leave the first scanning to completion in the background, competing for I/O with the search you actually asked for. A replaced run is now always signalled.

Lint floor moved to ruff 0.16 (#149)¶

Minimum ruff>=0.16.0 (was unpinned). 0.16.0 stabilizes sorted-min-max (FURB192) out of preview, and starts formatting Python code blocks inside Markdown, so ruff format now covers the docs tree alongside src/ and tests/.

Ruff’s default rule set is enabled (#149)¶

[tool.ruff.lint] no longer sets select. An explicit select replaces ruff’s curated default rule set rather than adding to it, so the project was opting out of every default rule it did not name. Its own linters now layer on top through extend-select, and each rule the wider set surfaces is either fixed or carries a per-file ignore stating why the code is deliberate.

Keep detail scroll status on the selected result (#148)¶

Queued scroll updates from a previously selected result no longer replace the detail status for the current result. Returning to a result still restores its last scroll position.

Class fields describe themselves in the API reference (#144)¶

The record, query, and CLI argument types now say what each field holds. They previously reached the rendered API reference as “Alias for field number 0” or as a bare name carrying only its type.

Focused default TUI layout boundaries (#148)¶

The default TUI now separates search and result streaming, detail interaction, and deterministic body rendering into focused modules. The detail scroll widget owns per-result positions, while the public layout type and key bindings remain unchanged.

CI actions updated to current majors¶

Workflow actions moved to their current major releases: actions/checkout v7, actions/setup-python v7, actions/setup-node v7, astral-sh/setup-uv v9.0.0, and dorny/paths-filter v4. Workflow behavior is unchanged, though setup-uv no longer prunes the uv cache, so the first run after this repopulates it.

Rich, selectable, copyable detail pane (#140)¶

The detail pane now renders Markdown and source-code prompt bodies as styled text off the UI thread, detecting the format by structure rather than guessing from headings. Rendered bodies are selectable (legible even on terminal-transparent ansi themes), and Markdown links are clickable in OSC-8 terminals. Two copy commands take either the rendered text or the raw source, an alt+r toggle swaps between them, and the body re-flows to the new width when the terminal is resized.

Highlight XML/markup prompt bodies (#140)¶

Agent-injected structured prompts such as <EPHEMERAL_MESSAGE> and <bash_command_reminder> now have their tags highlighted in the detail pane while the surrounding prose stays plain. Ordinary prose or code containing stray angle brackets (List<int>, a < b) is left untouched.

Visual select and yank in the detail pane (#140)¶

The detail pane gains tmux copy-mode-vi-style selection: v starts a visual selection, h/j/k/l move it, and y yanks the selected text to the clipboard.

Configurable keymaps (#140)¶

Key bindings are now customizable through a single keymaps.toml in your config directory. Vim, Emacs, and arrow-key bindings all work at once out of the box, with no mode to pick, and any binding can be remapped in the file.

mcp_swap.py doctor and use-local --env¶

The dev config-swap helper gains a read-only doctor subcommand that reports the effective MCP-swap environment: which server name each CLI points at (and a mismatch when the repo is registered under a name other than the derived default), un-reverted swaps and orphaned backups accumulating on disk, a state entry whose backup has gone missing, and auth-overriding env vars such as OPENAI_API_KEY. use-local also takes a repeatable --env KEY=VALUE to write env (e.g. an isolated data dir) into the server entry without a manual post-edit.

Pydantic bridge exports removed (#138)¶

Pydantic is now a required dependency, and the optional CLI serialization bridge has been removed. Library callers importing maybe_use_pydantic, maybe_build_pydantic, PydanticModule, PydanticTypeAdapter, or PydanticTypeAdapterFactory must migrate before upgrading.

Use serialize_search_record() or serialize_find_record() for record payloads and build_envelope() for CLI-style envelopes. These functions return JSON-compatible typed mappings directly; MCP schemas continue to use Pydantic at their explicit boundary.

Faster critical-path feedback (#138)¶

Agentgrep’s development checks now focus on the critical paths users depend on, giving contributors feedback in seconds without trading away release confidence. Broader and slower checks remain part of CI.

Faster local test feedback (#137)¶

Contributors now get faster local test feedback without giving up release confidence. The everyday suite focuses on high-signal coverage, while CI still runs the complete suite and project guidance points changes to the relevant deeper checks.

Preventive quality safeguards (#136)¶

agentgrep’s development checks now prevent several classes of maintenance debt from accumulating silently. New code must follow the project’s established lint and type-suppression standards, keeping future changes easier to review without changing user-facing behavior.

Large explorer searches stay responsive (#127)¶

The interactive explorer now streams and filters large result sets without building every row in advance. History recall, detail rendering, grep-style updates, and theme repaints remain usable while work continues, and canceled or superseded work can no longer repaint the current view.

Owned themes cover the whole explorer (#127)¶

agentgrep ui now includes agentgrep dark, light, and Tokyo Night themes with a first-run chooser and the existing /theme command. The selected theme is remembered across launches, including rapid changes made immediately before exit, while unrelated preferences remain intact.

The same semantic palette now drives inputs, result rows, query and find highlights, JSON and Markdown details, and the welcome screen. Each profile is tested for readable contrast, and decorative motion respects terminal focus and reduced-animation preferences.

The welcome screen provides runnable starting points (#127)¶

The empty explorer now offers clickable, syntax-highlighted query examples and an explicit Enter-to-search cue. Its wordmark adapts to the active theme and motion policy, while the complete welcome experience remains reachable in compact terminals.

Search inputs and public contracts stay aligned (#127)¶

Field-only and origin-only launch queries now keep keyboard focus on the visible primary input. Long or malformed input is bounded cleanly, terminal compatibility handling no longer leaks malformed mouse sequences into queries, and dumb terminals avoid automatic color escapes.

CLI and MCP search descriptions, schemas, selector validation, and examples now match the behavior of the shared query engine. MCP catalog diagnostics also avoid exposing local backend paths.

TUI layout and workflow controls retired (#125)¶

agentgrep ui now launches one supported HUD and search experience. Remove --layout and --workflow from saved invocations; F2 and F3 no longer cycle experimental components or add an internal pair to the title.

The layout/workflow implementation split remains intact. Python app factories can still choose an alternate initial pair for embedding and focused tests, while the shipped shell never switches it at runtime.

Explorer controls move into slash commands (#125)¶

The explorer now keeps its commands inside the primary input. Type / to open a compact menu, keep typing to filter it, or use /help to see the active command set. Ctrl-P no longer opens Textual’s screen-covering command palette.

The shared surface includes /clear, /exit, /keys, and /theme, with aliases and arguments shown directly in the menu. Unrecognized slash text stays available as a search instead of being swallowed as a command.

Content panes zoom without hiding controls (#125)¶

/maximize gives the results or detail pane the available body space while keeping the primary input and footer reachable. It follows the most recently used content pane, accepts an explicit results or detail target, and pairs with /minimize to restore the responsive split.

Clean explorer screenshots (#125)¶

/screenshot saves an automatically named SVG after clearing the command text and menu from the frame. The capture preserves the current search, results, theme, and zoom while keeping input and animation responsive.

Only the newest valid screenshot request can finish delivery, so a superseded capture cannot overwrite a newer view or escape from a layout that has already closed.

Theme changes and zoom navigation stay visible (#125)¶

Theme changes now repaint rows that were hidden by a filter before they return, so one result list cannot mix old and new colors. Directional navigation and detail-pane h / k bindings reveal their destination before moving focus, including in narrow and stacked terminals.

Clearing or starting a search while the detail pane is zoomed now restores the empty and searching panels instead of leaving a blank body.

Explorer scan progress stays truthful (#124)¶

The HUD and grep-log layouts now report the source being scanned and its parsed-record heartbeat while the results rule remains dedicated to filtered position and scroll state. Interrupted summaries identify the active source instead of treating its ordinal as completed work, and queued stale navigation updates cannot repaint a reset view.

The optional Ctrl-\ detail row names only an active store that has crossed the slow-source threshold. When a search finishes, it freezes the slowest completed store and exact duration without exposing local source paths.

Project-aware search reaches more agent histories (#112)¶

agentgrep now carries the model, working directory, and branch from more of the histories written by Codex, Cursor, Gemini, Grok, Pi, and Antigravity. Those facts power model:, cwd:, and branch: queries plus --cwd and --branch, so CLI, TUI, MCP, and Python consumers can distinguish otherwise similar conversations by where and how they ran.

--scope conversations and --scope all now reach readable state-backed histories that were previously invisible, while configuration and unreadable encrypted artifacts remain outside search. When a tool records only an ambiguous or hashed project identity, agentgrep preserves that uncertainty instead of inventing a working directory.

MCP hosts can auto-approve agentgrep calls (#112)¶

Every agentgrep MCP tool and resource now carries protocol-level behavior annotations: agentgrep is read-only, repeats the same call without extra effect, and reads only local on-disk agent stores rather than unbounded external entities. Hosts such as Claude Code, VS Code, and Cursor read those hints back when they list the server’s tools, so a search can run without a permission prompt on every call.

Codex conversations stay canonical (#112)¶

Codex rollouts now report the model slug the conversation actually used, including when that context appears after unusually large early records. Search also treats Codex’s state database as a fallback index rather than a second transcript, avoiding duplicate first prompts without hiding state-only metadata, previews, or explicitly selected state records.

Project context follows search results (#93)¶

agentgrep now carries project and workspace context with search records when the underlying agent store exposes it. CLI, TUI, JSON, NDJSON, and MCP results can show where a prompt came from — such as its working directory, repository, worktree, branch, or workspace hash — so same-looking sessions from different projects are easier to tell apart without opening the raw history files.

The same context powers project-aware search controls. --only-here, --here, origin query fields, and search origin filters can narrow or boost records from the current project while keeping symlinked checkouts, branch names, and remote URLs in their proper lanes.

Diagrammed event-stream architecture (#95)¶

The library docs now render Mermaid diagrams for the event-stream engine instead of relying on dense ASCII and one-line ordering notation. The architecture chart shows how one typed event stream feeds CLI, TUI, and MCP consumers, while the search and find sequence charts show the started, record, and finished envelopes that scripts can rely on.

The docs build now carries a local Mermaid toolchain, so the diagrams render as themed SVGs during the Sphinx build and keep captions and fallback text in the generated site. The same pass tightens API cross-references and highlights the query grammar as EBNF, making the reference pages easier to scan without changing runtime behavior.

Event-stream diagrams split for narrow screens (#96)¶

The event-stream architecture chart is now two top-to-bottom diagrams — one for the producer side, one for consumers — each with alt text, a stable link target, and a responsive policy, so they stay legible at phone width.

Inline commands and paths are highlighted (#96)¶

Inline mentions of agentgrep commands and file paths now carry syntax highlighting via the shared sphinx-gp-highlighting package, and the accelerator module layout renders as a highlighted directory tree.

Grok CLI and Antigravity in the MCP install picker (#97)¶

The MCP install docs’ client picker now covers Grok CLI and Antigravity (Google’s agy) alongside Claude, Codex, Gemini, and Cursor. Grok registers through its own grok mcp add verb; Antigravity has no such verb, so its mcpServers snippet is pasted into ~/.gemini/config/mcp_config.json.

Cross-host Cursor IDE discovery on WSL (#91)¶

Under WSL the Cursor IDE UI runs on the Windows host and writes its chat under the Windows profile, where a home-rooted search never looked. agentgrep now detects WSL and bridges to that Windows-side store, so search, grep, and find reach Cursor IDE conversations authored from the Windows UI. The bridge is auto-detected and costs nothing on every other platform; point AGENTGREP_WSL_USERS_ROOT at a non-default mount to override it. See Cursor IDE.

Pluggable explorer layouts and workflows (#88)¶

The interactive explorer (agentgrep ui) is now a thin shell over two independent axes you choose at launch and switch at runtime: a layout (how records are arranged on screen) and a workflow (what the primary input does). The familiar heads-up display is now the hud layout, joined by a new greplog that streams matches into an append-only, grep-style log; the live search workflow is joined by browse, where the input filters the already-loaded records in-memory instead of re-querying the engine.

Launch straight into a pair with agentgrep ui --layout greplog --workflow browse, or cycle the layout with F2 and the workflow with F3 while the explorer is open — the active layout · workflow pair shows in the title bar. Every combination drives the same engine over the same records. See TUI for details.

Faster, parallel-capable test suite (#86)¶

The suite drops redundant work — the documentation-widget tests share a single Sphinx build, and the import-chain regression test shares one interpreter snapshot — and gains an opt-in just test-fast that runs it across cores with pytest-xdist. The documentation-example sandbox now reuses a warm, read-only environment so those parallel runs stay green instead of cold-building a virtualenv per worker.

Explorer no longer freezes on find or filter (#84)¶

Stepping find-in-detail matches (n / N) and widening a results filter on a large result set could block the explorer’s input for a noticeable pause. Find-in-detail now reuses a cached syntax-highlighted body instead of re-highlighting it on every keystroke, and a filter rebuild reuses already-rendered rows instead of rebuilding the whole list.

Layered non-blocking TUI defense (#84)¶

The TUI’s single-threaded message pump now has a two-gate guard against work that would freeze it: a static check that follows same-class helper calls and classifies the callables Textual invokes on the pump, plus an opt-in runtime audit hook and a log-only heartbeat watchdog that defaults on for an interactive terminal so a wedged pump is observable. The textual-non-blocking-pump skill and ADR 0011: Non-blocking TUI invariants record the audit procedure and why a lint alone cannot reach 100%.

Development dependencies¶

The gp-libs documentation toolchain moved to 0.0.18 (was 0.0.17), with uv’s exclude-newer cooldown whitelisting gp-libs so doc builds pick it up, and the dev tooling packages were refreshed.

Reusable TUI widget architecture (#83)¶

The explorer’s controller logic — previously an oversized App object defined inside the build_streaming_ui_app factory closure — is now a module-level class reached through a narrow SearchInvoker engine seam, with agentgrep.ui.app reduced to a thin lazy-importing facade so the eager import agentgrep path stays Textual-free. The change is behavior-preserving and pinned by characterization tests. ADR 0012 also maps the capabilities of richer terminal UIs (pi, ink) onto Textual and concludes that Textual supplies every primitive agentgrep needs, so no native code is adopted; see ADR 0012: Reusable TUI widget architecture.

Search-history recall with Ctrl-R (#78)¶

The explorer’s search box now remembers what you’ve searched. Press Ctrl-R to open a recall panel, filter past queries as you type, preview the highlighted one, and drop it back into the box ready to run — no retyping. History persists across sessions; set AGENTGREP_NO_HISTORY to turn it off. See TUI.

Slash commands in the search box (#78)¶

Type / in the search box to open a command menu: /clear resets the search and results, /help lists the commands, and /exit quits — with aliases like /new and /quit. Anything that isn’t an exact command, such as a slash-prefixed path or a command followed by text, is searched as typed. See TUI.

Slimmer scanning progress (#78)¶

A running search now reports progress on a single line in the results header — a spinner, the current phase, and a compact percentage bar — instead of a multi-line status block, with the detailed per-source counts a keystroke away on the Ctrl-\ detail row. Before the first match lands, the results area shows a centered searching indicator. See TUI.

A pi-inspired redesign of the explorer TUI (#77)¶

The interactive explorer (agentgrep ui) has been reworked toward a calmer, pi- and Claude-Code-inspired aesthetic. The terminal background now shows through, the top header bar and visible scrollbars are gone, panes carry lightweight left-aligned section headers instead of boxes, and the search and filter inputs are reduced to a single rule. The empty explorer opens on a bare canvas with a short hint instead of empty chrome, and it stays responsive while a large record renders. See TUI and ADR 0011: Non-blocking TUI invariants.

Find within an open record (#77)¶

The detail pane gains an in-record find: press / or ctrl-f to open a find bar, type to highlight matches, and step through them with the current hit kept scrolled into view — correctly, even when long lines wrap. JSON records keep their syntax colours underneath the find highlight.

Staged ctrl-c in the TUI inputs (#77)¶

Inside the search, filter, and find inputs, ctrl-c now clears the field first; on an already-empty field it arms a brief “press ctrl-c again to exit” prompt before quitting, so a reflexive ctrl-c no longer drops you out of the explorer by surprise.

Layered module architecture behind a stable facade (#75)¶

The agentgrep package facade — which had accumulated the record types, per-agent parsers, store discovery, the query compiler, and the search/find engine in one module — is now a thin re-export shim over single-responsibility modules. The public import surface is unchanged: import agentgrep; agentgrep.SearchRecord and every documented name resolve exactly as before. An explicit __all__ and a module-boundary guard test keep the layering from eroding; see ADR 0010: Module boundaries and the facade re-export contract.

Wider storage coverage across the supported agents (#73)¶

find now inventories more of each agent’s on-disk storage — additional stores across Claude, Cursor, Gemini, Antigravity, Grok, Pi, and OpenCode — with the catalogue re-observed against current tool releases. Windsurf is documented for the first time, but flagged unsupported: its Cascade conversations are stored encrypted, so agentgrep records where they live without searching them.

New backend: VS Code (GitHub Copilot Chat) (#74)¶

agentgrep now searches VS Code’s built-in GitHub Copilot Chat — both the per-workspace conversation transcripts and the inline-edit (Ctrl+I) prompt history — across the Code, Insiders, VSCodium, and OSS editions. On WSL it also reaches chat written by a Windows-host VS Code, and results name the real project directory rather than an opaque storage folder.

Faster searches over large histories (#71)¶

Searching and browsing large Codex, Claude, and Cursor stores is faster, and the explorer stays responsive while a large record renders. The optional speedups extra (pip install agentgrep[speedups]) adds an orjson-accelerated decode path; results are identical with or without it.

A query language for search, grep, and find (#70)¶

All three commands accept a Lucene-style query language: combine terms with AND / OR / NOT (no field predicate required — ruff OR uv just works), quote "exact phrases", and filter by field with agent:, model:, role:, scope:, timestamp:, path:, and more. Predicates support field:* (present and non-empty), * / ? wildcards on text fields (model:gpt*), and date comparisons and ranges (timestamp:>2026-01-01, timestamp:[2026-01 TO 2026-03]). Bare term lists keep the original fast path untouched. See Query language.

Query language over MCP (#70)¶

The MCP search tool honors the same query language inline, the new agentgrep_query_language resource publishes the field and operator catalog (generated from the registry, so it never drifts from what the compiler accepts), and validate_query dry-runs a query’s syntax without running a search.

Live query completion in the TUI (#70)¶

The interactive explorer’s search bar and the now query-aware filter box offer inline ghost-text completion plus a keyword dropdown for field names and enum values (agent:co → agent:codex). Completion is query-language only — no record text or IDs leak into the suggestions.

Query syntax highlighting in the CLI, TUI, and docs (#70)¶

Query examples are syntax-highlighted everywhere the language appears: the CLI --help examples (field, operator, value, and wildcard each in their own color), the TUI search and filter boxes as you type, and documentation code blocks via a new agentgrep-query Pygments lexer. All three share one grammar.

agentgrep search shows help when run without terms (#70)¶

Running agentgrep search with no terms now prints the subcommand’s help and examples instead of ranking every stored record, mirroring bare agentgrep. agentgrep search --ui still opens the explorer.

Query-language reference and design rationale (#70)¶

A refreshed Query language page documents the full grammar — phrases, field-exists, wildcards, dates, and the opt-in gate — and ADR 0007 records how agentgrep’s substring/regex matching model compares to Tantivy and why the query language stops where it does.

Resumable MCP result pages (#64)¶

MCP search and find responses now report whether a scan finished or stopped at the page limit, and hand back an opaque cursor to fetch the next page. Each result carries an opaque ref, and the new inspect_result tool reads the records behind a ref so agents can drill into a hit without reconstructing local file paths.

Antigravity CLI and IDE backends (#67)¶

agentgrep now searches Google Antigravity. Because the agy CLI and the Antigravity IDE keep their data in unrelated trees under the shared ~/.gemini home, agentgrep models them as two backends: --agent antigravity-cli searches the CLI’s history.jsonl prompt recall log by default, while --agent antigravity-ide covers the IDE’s local artifacts. The protobuf conversation transcripts on both sides (no published schema) and the IDE’s Markdown brain and skill files (planning notes, not chat history) are catalogued as inspectable-only stores, reachable on request but kept out of default search. See Antigravity CLI and Antigravity IDE for the split layout.

Result cap --limit for grep (#53)¶

grep now takes --limit N as its primary result cap, keeping -m and --max-count as grep-family aliases.

Home-relative path: predicates (#53)¶

path: predicates accept current-user ~/~/... prefixes.

find --print0/--absolute-path emit real filesystem paths (#53)¶

find --print0 and --absolute-path now emit real filesystem paths for shell pipelines like xargs -0, instead of the privacy-collapsed ~ display paths they produced before. Text and JSON output stay collapsed.

Documentation examples tested as pytest items (#53)¶

A new pytest_documentation plugin runs the docs’ console examples, fastmcp.json, and the just doctest recipe as pytest items against sandboxed fake agent history, so broken copied commands fail the test gate.

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.