hatch3r-cli-fd

fd

User-friendly find replacement, gitignore-aware

§0 — Ambiguity & Safety Gate (P8 B1)

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

• Scope: when the search root or pattern matches more files than intended (a bare glob over the repo root, -H including dotfiles), confirm the target path before running.
• Irreversibility: fd is read-only on its own, but fd … -x / -X runs an arbitrary command per match. fd <pat> -x rm or any mutating --exec is destructive and fan-out-wide — confirm the command and the match set before running, and prefer printing the list first.
• Ambiguity: when the request maps to two or more matchers with materially different result sets (regex vs -g glob, -e ext vs path regex), ask which one.

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: .claude/rules/fan-out-discipline.md (P8 B2).

When to Use

Reach for fd when the task is in the search 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

fd '\.test\.ts$' src/

Regex match against the path tail — locates every test file under src/ without traversing node_modules or .git (gitignore-aware by default).

fd -e ts -e tsx --exec wc -l

Extension filter plus parallel --exec — one process per match, returns line counts for sizing audits.

fd -H -E .git -E node_modules 'config'

Includes hidden files (-H) and explicitly excludes vendor trees — useful when scanning dotfiles for stale config.

fd --changed-within 7d -e md

Time-windowed query for recent edits — pairs with gh pr list to spot undocumented changes.

fd 'SKILL\.md$' skills/ -x rg -l 'placeholder'

Pipeline: locate every SKILL.md, then rg-search each for a marker string in one parallel batch.

Wrong Choice When

• Don't reach for fd when the recursive predicate needs POSIX find features like -mtime +N -delete, -path with mixed Boolean operators, or NFS-mount handling. Reach for system find.
• Don't use fd as a content searcher — it matches paths, not file bodies. Reach for ripgrep (hatch3r-cli-ripgrep), optionally piped after fd for filename pre-filtering.
• Don't use fd against a system-wide indexed search ("which package owns this file?"); it walks the live filesystem each call. Reach for locate / mlocate.

Alternatives

Tool	When to prefer
find (POSIX)	Mixed predicates with -and/-or, -mtime, -prune, or actions like -delete and -execdir.
locate	Pre-indexed lookups across the entire filesystem (no live walk).
ripgrep (hatch3r-cli-ripgrep)	When you want content matches, not path matches — fd ... -x rg if both.
git ls-files	Restrict to tracked files only; ignores untracked even if not in .gitignore.

Detection / Install

Verify with:

command -v fd

Install (macOS — default for this machine):

# brew
brew install fd

Install (Linux):

# apt
sudo apt install fd-find

Install (Windows):

# scoop
scoop install fd

Homepage: https://github.com/sharkdp/fd