Filesystem search

terminal-tools provides two structured search tools: terminal_rg (ripgrep for content) and terminal_glob (find files by name/glob). Predicate queries (mtime/size/type) and everything else (tree, stat, du) are just terminal_exec.

When to use what

| Task | Tool | |---|---| | Find code/text matching a pattern (project tree or any path) | terminal_rg (gitignore-aware; defaults to your session workdir) | | Find files by name/glob (any path) | terminal_glob | | Find files by mtime/size/type predicate | terminal_exec("find ...") (see references/find_predicates.md) | | List a directory | terminal_exec("ls -la /path") | | Tree view | terminal_exec("tree -L 2 /path") | | Single-path stat | terminal_exec("stat /path") | | Disk usage | terminal_exec("du -sh /path") or terminal_exec("du -h --max-depth=2 /") | | Count matches across files | terminal_rg(pattern, count=True via extra_args=["-c"]) |

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

| Flag | Effect | |---|---| | -tpy (type_filter="py") | Only Python files | | -uu | Don't respect any ignores (incl. .git/) | | --multiline (extra_args) | Allow regex spanning lines | | --max-count (max_count) | Stop after N matches per file | | --max-depth (max_depth) | Limit recursion | | -w (extra_args) | Whole word match | | -F (extra_args) | Fixed string (no regex) |

See references/ripgrep_cheatsheet.md for the long form.

terminal_glob — find files by name

Lists files matching a glob, gitignore-aware (backed by rg --files). The pattern is widened for you so a bare stem Just Works — the actual glob run is returned as expanded_pattern:

• lk_scan_post_reactors → matched as **/*lk_scan_post_reactors* (recursive substring)
• *.py → matched as **/*.py (recursive by default)
• src/**/*.py → used verbatim

# Find a file by stem anywhere under a tree
terminal_glob(pattern="lk_scan_post_reactors", path="core/framework/skills")

# All YAML configs under /etc
terminal_glob(pattern="*.yaml", path="/etc")

# Include .gitignored / hidden / build-cache files
terminal_glob(pattern="*.log", path=".", include_ignored=True)

For predicate queries (modified in last N days, larger than N MB, only dirs/symlinks), terminal_glob is the wrong tool — drop to terminal_exec("find ..."). See references/find_predicates.md.

Output truncation

Both tools return truncated: true when output exceeded the inline cap. For terminal_rg, matches were dropped (refine the pattern or narrow the path); for terminal_glob, results past max_results (default 1000) were dropped — the search stops early at the cap, so narrow the pattern rather than raising it. terminal_glob also returns timed_out: true (with the partial results it gathered) when the walk exceeded its deadline.

Anti-patterns

• terminal_rg is the project search tool — gitignore-aware and returns structured matches; use it for in-project search as well as raw paths.
• Don't reach for terminal_glob 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 hand-roll terminal_exec("find ... -name ...") for a plain name search — use terminal_glob. Reserve terminal_exec("find ...") for mtime/size/type predicates.