# 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.0a4 (Yet to be released)

<!-- KEEP THIS PLACEHOLDER - DO NOT REMOVE OR MODIFY THIS LINE -->
_Notes on the upcoming release will go here._
<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->

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