kavin525zhang/llm_reasoning_framework/terminal-tools-fs-search

Filesystem search

terminal-tools provides two structured search tools: terminal_rg (ripgrep for content) and terminal_find (find for predicates). Everything else (tree, stat, du) is just terminal_exec.

When to use what

terminal_rg — content search

ripgrep is fast, gitignore-aware, and has a deep flag surface. The structured wrapper exposes the most useful flags directly; extra_args covers the rest.

Common patterns

# All Python files containing "TODO"
terminal_rg(pattern="TODO", path=".", type_filter="py")
 
# Case-insensitive, with context
terminal_rg(pattern="error", path="/var/log", ignore_case=True, context=2)
 
# Search hidden files (rg ignores them by default)
terminal_rg(pattern="api_key", path="~", hidden=True)
 
# Don't respect .gitignore (find files git would ignore)
terminal_rg(pattern="generated", path=".", no_ignore=True)
 
# Multi-line pattern (e.g., function definitions spanning lines)
terminal_rg(pattern=r"def\s+\w+\(.*\n.*\n", path="src", extra_args=["--multiline"])
 
# Specific filename glob
terminal_rg(pattern="version", path=".", glob="*.toml")

rg flag idioms

See references/ripgrep_cheatsheet.md for the long form.

terminal_find — predicate search

find excels at "files matching N criteria". The wrapper surfaces the most common predicates; combine via the structured arguments.

# All .log files modified in the last 7 days, larger than 1MB
terminal_find(path="/var/log", iname="*.log", mtime_days=7, size_kb_min=1024)
 
# All directories named ".git" (find Git repos under a tree)
terminal_find(path="~/projects", name=".git", type_filter="d")
 
# Only the top three levels
terminal_find(path="/etc", max_depth=3, type_filter="f")
 
# Symlinks
terminal_find(path=".", type_filter="l")

See references/find_predicates.md for combinations not directly exposed.

Output truncation

Both tools return truncated: true when their output exceeded the inline cap. For terminal_rg, this means matches were dropped (refine the pattern or narrow the path); for terminal_find, results past max_results (default 1000) are dropped. Tighten predicates rather than raising the cap.

Anti-patterns

• Don't `terminal_rg` your project tree — files-tools.search_files is project-aware and ranks results.
• Don't reach for `terminal_find` to list one directory — terminal_exec("ls -la /path") is shorter.
• Don't use `terminal_exec("grep ...")` when terminal_rg exists — rg is faster, gitignore-aware, and returns structured matches.
• Don't use `terminal_exec("find ...")` to invent your own predicate combinations — use terminal_find and report missing capabilities.