# 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.0a3 (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.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)
