| name | tool-fzf |
| description | Use fzf for interactive fuzzy selection from files, branches, and command output. Trigger when a human-in-the-loop selection step is needed inside terminal workflows. |
tool-fzf
When To Use
- Add interactive selection to shell workflows.
- Narrow large candidate lists quickly with fuzzy matching.
- Run non-interactive fuzzy filtering in scripted pipelines.
Trusted Commands
fzf
git branch --all | fzf
fd -t f | fzf
fzf --preview 'bat --color=always {}'
printf '%s\n' foo bar baz | fzf --filter 'ba'
fzf --multi
Safe Defaults
- Use clear prompts and scoped input lists.
- Prefer
--filter when running without an interactive TTY.
- Handle cancel/no-result paths explicitly in scripts.
Common Pitfalls
- Exit code
130 indicates cancel, not regular no-results.
--multi emits newline-separated selections and needs downstream handling.- Environment defaults such as
FZF_DEFAULT_COMMAND can change behavior.
Output Interpretation
- Interactive mode prints selected line(s) to stdout.
--filter prints matches non-interactively and returns 0/1.
Why It Matters For Agents
- Supports both human-driven and fully scripted fuzzy selection.
- Enables ergonomic choice workflows without custom UI development.
Repo Conventions
- Use fzf for user-choice steps, not mandatory automation paths.
- Keep deterministic fallbacks for non-interactive environments.
Trigger Examples
- Should trigger: "Let me choose a branch interactively from a list."
- Should trigger: "Add a fuzzy file picker to this script."
- Should not trigger: "Run a static shell linter on this script."
