| name | search-and-navigation |
| description | Fast repo navigation with ripgrep, fd, bat, tree, eza, zoxide, and delta. Use for text search and file discovery — see search-tool-selection for tool choice. |
Search and navigation
Tool choice first: search-tool-selection — fd → rg → read slice.
Purpose
Find files and text quickly with gitignore-aware tools and bounded reads.
When to Use
- Locate files by name (
fd)
- Search literals/regex in contents (
rg)
- Orient in a new directory (
tree, eza)
- Read a code slice (
bat, sed -n)
Required Tools
rg, fd, bat; optional tree, eza, zoxide, delta, fzf (humans only).
Install
Install blocks are shared — See install-blocks.md.
Windows PowerShell
Use winget blocks from the reference when provisioning a new machine.
WSL2 Ubuntu
Use apt/curl blocks from the reference; symlink fdfind → fd if needed.
macOS
Use Homebrew blocks from the reference.
Common Commands
fd -e py -e md .
rg "pattern" src/ --glob '!node_modules' -n --max-count 40
tree -L 3 -I 'node_modules|dist|build|.git'
bat --line-range 1:120 path/to/file.py
git diff -- path/to/file | delta
Agent-Safe Patterns
- See bounded-output-patterns.md.
- Do not use
fzf in agent loops (interactive TTY).
- Prefer IDE Grep/SemanticSearch/Glob when already bound in Cursor.
Commands Requiring Confirmation
See commands-requiring-confirmation.md.
Troubleshooting
rg slow: narrow path, add -g, increase excludes for node_modules, dist, build.
fd empty: check cwd is repo root.
Windows Notes
WSL2 Notes
Verification Checklist