hatch3r-cli-fzf

fzf

Interactive fuzzy finder for TTY pickers

§0 — Ambiguity & Safety Gate (P8 B1)

Before invoking fzf, resolve these via agents/shared/user-question-protocol.md (default behavior, not exception-driven):

• Scope: confirm the input stream piped into fzf is the intended candidate set; a wrong upstream command silently changes what gets ranked.
• Irreversibility: fzf only selects — it never mutates files. The real hazard is invoking interactive fzf (no --filter) in a non-TTY context (CI, agent loop): it blocks on stdin forever. Always use --filter headless mode from an autonomous agent; treat any downstream action on the selection (the command you pipe the pick into) under its own irreversibility check.
• Ambiguity: when more than one match scores closely and the workflow needs a single deterministic pick, pin it with --filter … | head -1 rather than relying on interactive choice.

Fan-out Discipline (P8 B2)

Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: rules/hatch3r-fan-out-discipline.md (P8 B2).

When to Use

Reach for fzf when the task is in the interactive category and the agent would otherwise call an MCP tool or read large outputs into context.

Token Cost

CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB. Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.

Recipes

fzf --filter 'auth' < paths.txt

Headless mode — ranks lines by fuzzy match score and prints them in order; no TTY needed. This is the agent-safe entrypoint.

git branch --format='%(refname:short)' | fzf --filter main

Score branch names against main; pipe to head -1 to pick the best match deterministically.

rg -l 'TODO' . | fzf --filter 'src/cli'

Re-rank a ripgrep file list by proximity to a fuzzy hint; combine with head for a deterministic top pick.

fzf --filter 'auth' --print0 < paths.txt | xargs -0 wc -l

Stream NUL-delimited matches to a downstream pipeline — safe across filenames with spaces.

fzf < paths.txt

Interactive picker — only useful in a human TTY; do not call this form from an autonomous agent.

Wrong Choice When

• Running in a non-TTY context (CI, agent loop) — interactive fzf will hang on stdin; always use --filter headless mode.
• The ranking needs semantic understanding (synonyms, embeddings) — fzf is character-level fuzzy; reach for an embedding-based tool.
• A simple grep -F or rg --files | head would already return the right answer — no need to layer scoring on top.

Alternatives

Tool	When to prefer
skim (sk)	Need a Rust binary with similar fuzzy scoring and the same --filter headless mode.
rg --files | head	Already filtered; want stable lexicographic order rather than fuzzy ranking.
grep -F	Exact substring match; no scoring needed.

Detection / Install

Verify with:

command -v fzf

Install (macOS — default for this machine):

# brew
brew install fzf

Install (Linux):

# apt
sudo apt install fzf

Install (Windows):

# scoop
scoop install fzf

Homepage: https://github.com/junegunn/fzf