# Changelog

To install the unreleased agentgrep version:

[pip](https://pip.pypa.io/en/stable/):

```console
$ pip install --user --upgrade --pre agentgrep
```

[pipx](https://pypa.github.io/pipx/docs/):

```console
$ pipx install \
    --suffix=@next \
    --pip-args '\--pre' \
    --force \
    'agentgrep'
```

Run the suffixed executable as:

```console
$ agentgrep@next [command]
```

[uv](https://docs.astral.sh/uv/):

```console
$ uv add agentgrep --prerelease allow
```

[uvx](https://docs.astral.sh/uv/guides/tools/):

```console
$ uvx --from 'agentgrep' --prerelease allow python
```

## agentgrep 0.1.0a19 (Yet to be released)

<!-- KEEP THIS PLACEHOLDER - DO NOT REMOVE OR MODIFY THIS LINE -->

<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->

## agentgrep 0.1.0a18 (2026-06-06)

agentgrep 0.1.0a18 makes searches substantially faster across every
backend: lines that cannot match are skipped before parsing, limited
searches read history files newest-first and stop early, and the MCP
server and TUI reuse earlier scan work between searches. It also fixes
three search-results bugs — boolean `OR` queries dropping valid
matches, project folder-name searches coming back empty, and Cursor
IDE workspace history going missing from broad searches.

### What's new

#### 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.

### Fixes

#### 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.

### Development

#### 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.

## agentgrep 0.1.0a17 (2026-06-04)

agentgrep 0.1.0a17 makes searches fast on huge Cursor IDE databases.
The `state.vscdb` reader now scans keys first and fetches values only
for chat and prompt entries, so multi-gigabyte databases stop funneling
unrelated editor data through memory on every search.

### Fixes

#### 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.

## agentgrep 0.1.0a16 (2026-06-04)

agentgrep 0.1.0a16 fixes broad searches silently skipping Cursor IDE's
SQLite history store, so Cursor IDE matches reliably show up in results
again. It also adds a local, privacy-safe engine profiling workflow — a
component profiler script plus benchmark capture and analysis — for
gathering bottleneck evidence without exposing prompt text, raw argv,
or local paths.

### Fixes

#### 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.

### Development

#### 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.

## agentgrep 0.1.0a15 (2026-05-31)

agentgrep 0.1.0a15 speeds up broad lookup paths by separating lightweight
search discovery from metadata-rich source inventory. Search, grep, find, and
MCP lookup paths now avoid version and shape work when they only need parseable
source handles.

### What's new

#### 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.

## agentgrep 0.1.0a14 (2026-05-31)

agentgrep 0.1.0a14 makes prompt search the default search scope and
requires explicit opt-in for full conversation records. This release
renames the search breadth selector to `scope` across the CLI, MCP,
query language, and Python library so prompt-history logs are no
longer confused with conversation history.

### Breaking changes

Search and grep now use `--scope`, not `--type`, for prompt versus
conversation breadth. `find --type` is unchanged because it still
filters discovered files and stores.

Before:

```console
$ agentgrep grep "release notes" --type history
```

After:

```console
$ agentgrep grep "release notes" --scope conversations
```

MCP search requests now send `scope` instead of `search_type`, and
library callers construct {class}`~agentgrep.SearchQuery` with
`scope=...`.

### What's new

#### 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.

## agentgrep 0.1.0a13 (2026-05-31)

agentgrep 0.1.0a13 adds OpenCode (anomalyco/opencode, formerly
sst/opencode) as a searchable backend, reachable from both the CLI
(`--agent opencode`) and the MCP server. Unlike the JSONL-transcript
backends, OpenCode keeps every conversation in one SQLite database
that agentgrep reads relationally by joining its session, message, and
part tables. See {doc}`/backends/opencode` for the store layout and
record schema.

### What's new

#### OpenCode backend (#30)

agentgrep now searches [OpenCode](https://github.com/anomalyco/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
{doc}`/backends/opencode` for details.

## agentgrep 0.1.0a12 (2026-05-31)

agentgrep 0.1.0a12 adds Pi (the earendil-works "Pi Agent Harness") as
a searchable backend, reachable from both the CLI (`--agent pi`) and
the MCP server. Pi keeps each conversation as a single append-only
JSONL session file with no separate prompt-history log or SQLite
index, so prompts and history are read straight from the transcript.
See {doc}`/backends/pi` for the store layout and record schema.

### What's new

#### Pi backend (#28)

agentgrep now searches [Pi](https://github.com/earendil-works/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
{doc}`/backends/pi` for details.

## agentgrep 0.1.0a11 (2026-05-31)

agentgrep 0.1.0a11 splits the Cursor backend into two agents —
`cursor-cli` (the `cursor-agent` terminal CLI) and `cursor-ide` (the
desktop app) — matching their disjoint data homes and on-disk formats.
It also adds three stores the single-agent model had missed: the Cursor
CLI prompt-history log, per-workspace IDE history, and a best-effort
protobuf chat reader. Retiring the `cursor` agent is a breaking change
— see below.

### Breaking changes

#### 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:

```console
$ agentgrep search foo --agent cursor
```

After — the terminal agent:

```console
$ agentgrep search foo --agent cursor-cli
```

After — the desktop app:

```console
$ 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 {doc}`/backends/cursor-cli` and {doc}`/backends/cursor-ide`.

### What's new

#### 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.

## agentgrep 0.1.0a10 (2026-05-31)

agentgrep 0.1.0a10 is a scope-tightening release — both changes are
removals. It drops the prefilter-bypassing `search --regex` / `--any`
flags and `grep -L` (they bypassed the ripgrep prefilter and forced a
full-corpus scan), and removes the stdin-only `fuzzy` subcommand, which
sat outside agentgrep's prompt/history search scope and only
approximated fzf. `grep` and `find` stay regex-by-default and `search`
keeps its rapidfuzz ranking; pipe through `fzf` directly for fuzzy
filtering.

### Breaking changes

#### 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 {tooliconl}`search` and {tooliconl}`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:

```console
$ agentgrep grep foo | agentgrep fuzzy bar
```

After — pipe through `fzf` directly:

```console
$ agentgrep grep foo | fzf --filter bar
```

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

## agentgrep 0.1.0a9 (2026-05-30)

agentgrep 0.1.0a9 reports how each discovered source's version was
detected. App-version context, data-shape version, detection
strategy, confidence, and concise evidence now ride along with source
discovery and the MCP `list_sources` payload. The release also
restores `find --type` filtering and corrects `fuzzy` output for
`--json` / `--ndjson` and empty queries.

### What's new

#### 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.

### Fixes

- `agentgrep find --type` (`prompts`, `history`, `sessions`) now returns the matching stores again instead of nothing. (#31)
- `agentgrep fuzzy --json` and `--ndjson` now emit structured output (scored matches) instead of silently printing plain text. (#31)
- `agentgrep fuzzy` with an empty query now passes every line through (like `fzf --filter ''`) instead of emitting nothing. (#31)

## agentgrep 0.1.0a8 (2026-05-25)

agentgrep 0.1.0a8 ships Grok CLI as the fifth searchable backend and
introduces a new documentation section documenting every backend's
store layout and record schema. Prompt history, chat transcripts, and
the session-search SQLite index are all searchable out of the box.

### What's new

#### 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 {doc}`/backends/index` section provides a support matrix and
per-engine pages ({doc}`/backends/codex`, {doc}`/backends/claude`,
{doc}`/backends/cursor-cli`, {doc}`/backends/cursor-ide`,
{doc}`/backends/gemini`, {doc}`/backends/grok`) documenting store
layouts, adapter IDs, and record schemas.

### Dependencies

Minimum `grok-cli v0.1.219` observed for the Grok backend stores.

## agentgrep 0.1.0a7 (2026-05-25)

### What's new

#### `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.

## agentgrep 0.1.0a5 (2026-05-23)

The CLI grows from three subcommands to five (`grep`, `fuzzy`,
plus fd-shaped `find` flags), threads a Lucene-style query
language through `search`/`grep`/`find`, and swaps the engine
for a streaming event-stream producer the CLI and TUI consume
live.

### Breaking changes

#### 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.

### What's new

#### 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.

### Documentation

- History page renders the changelog inline. (#9)
- Sidebar groups pages by section with expandable children. (#9)
- Getting Started section consolidates quickstart, installation, MCP-client setup, and configuration pages. (#9)
- Development section at `/dev/` for internals references (benchmark harness, storage catalogue). (#9)

### Development

#### `scripts/benchmark.py` (#9)

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

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

## agentgrep 0.1.0a4 (2026-05-21)

agentgrep 0.1.0a4 lifts the CLI to a first-class documentation
surface. The docs site gains a `/cli/` section above Library in the
sidebar, with per-subcommand reference pages auto-generated from the
argparse tree and dedicated sections describing `--json` / `--ndjson`
output for shell pipelines and non-MCP agents. A new `{cli-install}`
widget sits next to the existing MCP installer on the homepage so
terminal users see the right install snippet on first paint.

### What's new

#### 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 {class}`~agentgrep.SearchRecord` and
{class}`~agentgrep.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.

### Fixes

#### 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.

### Development

The `sphinx-autodoc-argparse` Sphinx extension is added to the `dev`
and `docs` dependency groups to drive the per-subcommand argparse
rendering. The `make_cooldown_days_slot_filter` Jinja helper now
emits the shared `ag-cooldown-days` class on cooldown-day spans
instead of the mcp-prefixed variant — no visual change, but the
filter output is widget-agnostic, so `{cli-install}` panels can reuse
the same sentinel mechanism.

#### `agentgrep.ui` subpackage (#7)

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

## agentgrep 0.1.0a3 (2026-05-17)

agentgrep 0.1.0a3 promotes the MCP server to a first-class
product surface alongside the library. Eight new MCP tools and
three new resources expose the full catalog and discovery layer
to clients without dropping back to the CLI; a tabbed install
widget on both the MCP and library landing pages picks the right
snippet for each client, install method, and config scope. The
docs sidebar now treats Library and MCP as top-level sections
rather than members of a Packages group.

### What's new

#### Eight new MCP tools

The MCP server gains {tooliconl}`list_stores`,
{tooliconl}`get_store_descriptor`, {tooliconl}`inspect_record_sample`,
{tooliconl}`list_sources`, {tooliconl}`filter_sources`,
{tooliconl}`summarize_discovery`, {tooliconl}`recent_sessions`, and
{tooliconl}`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 {class}`~agentgrep.stores.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
{func}`~agentgrep.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
{doc}`library/index` and {doc}`mcp/index` carrying the install
widgets. Old `/packages/agentgrep/*` URLs redirect to
`/library/*`.

### Development

#### `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.

## agentgrep 0.1.0a2 (2026-05-17)

agentgrep 0.1.0a2 fixes silent "No matches found." failures for
users whose `~/.claude`, `~/.codex`, or `~/.cursor` sits inside a
dotfile-managed tree, adds search support for the Cursor CLI
agent's per-project transcripts and Google Gemini CLI's session
and prompt-log files, and lands the first public storage
catalogue — a Pydantic-modelled registry of every prompt and
history store agentgrep knows about, with version provenance
baked into each entry. `agentgrep search --agent gemini` is now
a valid CLI invocation; `--agent cursor` returns CLI-agent
matches alongside Cursor IDE results. See {ref}`storage-catalog`
for the new reference page.

### What's new

#### 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
{func}`~agentgrep.store_catalog.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 {mod}`agentgrep.stores` module exposes
{class}`~agentgrep.stores.StoreDescriptor` and
{class}`~agentgrep.stores.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
{class}`~agentgrep.stores.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.

### Fixes

#### 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.

### Documentation

#### New storage-catalog reference page (#4)

A new {ref}`storage-catalog` 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.

## agentgrep 0.1.0a1 (2026-05-17)

agentgrep 0.1.0a1 ships the first interactive surface for the
package. `agentgrep search --ui` now mounts a Textual app
immediately and streams results as they're discovered, with
vim-style navigation, format-aware rendering for JSON and Markdown
chat content in the detail pane, and a smart `Ctrl-C` that cancels
an in-flight search before quitting the app.

### What's new

#### 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.

### Development

- Type-checker switched from mypy to ty. Local recipes, lock file,
  and CI all run `uv run ty check` now. (#1)
