agentgrep fuzzy¶

The agentgrep fuzzy command is a non-interactive fuzzy filter shaped like fzf --filter. It reads candidate lines from stdin, scores them against your query, and emits the matches in descending score order. Use it as the narrowing stage at the tail of a pipeline.

Defaults follow fzf: fuzzy matching with the v2 algorithm, smart-case (case-insensitive unless the query has uppercase), extended-search syntax (foo !bar, ^foo, bar$, 'foo), and score-descending sort.

Examples¶

Narrow grep output to lines that fuzzy-match a phrase:

$ agentgrep grep -F . | agentgrep fuzzy 'config bliss'

Exact substring matching instead of fuzzy:

$ agentgrep fuzzy --exact -i 'design notes' < transcript.txt

Match in a specific tab-separated column (1-indexed):

$ agentgrep find -l | agentgrep fuzzy --delimiter $'\t' --nth 4 jsonl

Print the query as the first output line (fzf’s --print-query):

$ agentgrep fuzzy --print-query design < transcript.txt

Open the Textual explorer pre-filled with the fuzzy query:

$ agentgrep fuzzy design --ui

No-input behavior¶

When agentgrep fuzzy is invoked with no QUERY positional, no -f filter, AND no piped stdin (i.e. you typed agentgrep fuzzy into an interactive shell), the subcommand prints its usage and exits with status 2. There is no interactive fzf-style TUI fallback — for interactive browsing reach for agentgrep ui or the --ui overlay on any other subcommand.

Command¶

Usage¶

usage: agentgrep fuzzy [-h] [--agent {codex,claude,cursor,gemini,all}]
                       [-f QUERY] [-i | --no-ignore-case | --smart-case] [-e]
                       [--no-extended] [--algo {v1,v2}]
                       [--tiebreak {length,begin,end,index,chunk}] [--no-sort]
                       [-d DELIM] [-n N] [--with-nth N] [--print-query]
                       [--read0] [--print0] [--json | --ndjson | --ui]
                       [query]

Positional Arguments¶

query¶

Fuzzy query (also accepted via -f/--filter)

Default: None

Options¶

--agent¶

Limit results to a specific agent; repeatable

Default: []
Choices: codex, claude, cursor, gemini, all

-f, --filter QUERY¶

Explicit filter query (overrides the positional)

Default: None

-e, --exact¶

Use exact substring matching instead of fuzzy

Default: False

--no-extended¶

Disable extended-search tokens (``foo !bar`` etc.)

Default: False

--algo¶

Fuzzy match algorithm (default: v2)

Default: v2
Choices: v1, v2

--tiebreak¶

Score tiebreak rule (default: length)

Default: length
Choices: length, begin, end, index, chunk

--no-sort¶

Preserve input order instead of sorting by score (fzf's ``+s``)

Default: False

-d, --delimiter DELIM¶

Field delimiter (default: whitespace)

Default: None

-n, --nth N¶

Limit matching to the Nth field (1-indexed)

Default: None
Type: int

--with-nth N¶

Display only the Nth field

Default: None
Type: int

--print-query¶

Prepend the query as the first line of output

Default: False

--read0¶

Treat stdin as NUL-delimited

Default: False

--print0¶

Separate output records with NUL instead of newline

Default: False

-i, --ignore-case¶

Force case-insensitive matching

Default: False

--no-ignore-case¶

Force case-sensitive matching (fzf's ``+i``)

Default: False

--smart-case¶

Smart-case (default): case-sensitive only when query has uppercase

Default: False

--json¶

Emit one JSON document

Default: False

--ndjson¶

Emit one JSON object per line

Default: False

--ui¶

Launch a read-only UI

Default: False

Exit codes¶

0 — at least one input line matched the filter
1 — no lines matched
2 — invalid usage (no QUERY and no piped stdin)

Extended-search syntax¶

The default --no-extended flag toggles fzf’s extended-search grammar:

A bare token must appear in the line (substring match)
!token excludes lines containing token
^token anchors to the line prefix
token$ anchors to the line suffix
'token forces an exact substring match (no fuzzy fallback)

Tokens are whitespace-separated. A line matches when every positive token’s predicate is satisfied and no negative token’s predicate is. Pass --no-extended to treat the query as a single literal pattern.

Field selection¶

--delimiter, --nth, and --with-nth mirror fzf’s field-selection model. With --delimiter $'\t' and --nth 2, only the second tab-separated field is scored. With --with-nth 3, only the third field is displayed even though scoring happens against the full line. Together they let you fuzzy-narrow tabular pipelines (e.g. agentgrep find --list-details) by column.

NUL-delimited I/O¶

Pass --read0 to treat stdin as NUL-delimited (for input from agentgrep find --print0, xargs -0, etc.). Pass --print0 to separate output records with NUL — useful when piping back into another xargs -0 consumer or any tool that needs paths with embedded spaces.

Interactive UI¶

Pass --ui to open the Textual explorer pre-filled with the fuzzy query.