--- name: hive-terminal-tools-fs-search-43ee5d53deb0 description: Use terminal_rg / terminal_glob for all filesystem search — your project tree as well as system configs, /var/log, /etc, archive contents. Teaches the rg vs glob vs terminal_exec("find/ls/du/tree") split, common rg flag combos for code/logs/configs, glob patterns for finding files by name, the rule that mtime/size/type predicate queries drop to terminal_exec("find ..."), and that for tree views or single-file stat info you should just use terminal_exec instead of inventing a tool. Read before reaching for raw shell to grep or find anything. metadata: author: hive type: preset-skill version: "1.0" --- # 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 matching lines in returned results | `terminal_rg(...).total` (check `truncated` before treating it as complete) | ## `terminal_rg` — content search ripgrep is fast, gitignore-aware, and has a deep flag surface. The structured wrapper exposes common search flags directly; `extra_args` accepts additional flags compatible with JSON output. Output modes such as `--count` and `--files-with-matches` are not compatible with this structured interface; use the CLI when that output is needed. Quickstart installs and verifies ripgrep. Existing installations can be repaired with `uv run scripts/ensure_ripgrep.py --install` from the repository root. The runtime also checks Windows package-manager locations and current registry PATH entries; `HIVE_RIPGREP_PATH` can select an absolute executable path. Startup logs report the executable and version, or instructions to fix the missing dependency. If ripgrep is unavailable, `terminal_rg` returns `code="ripgrep_required"` without searching by default. For an approximate search, explicitly set `allow_fallback=True`: this uses Python regex, a limited filetype table, and basename globs, and does **not** honor `.gitignore`. Even with opt-in, context, `extra_args`, unknown filetypes and complex globs require ripgrep and return an error. Inspect `fallback_limitations`; do not treat approximate results as a gitignore-aware inventory. With `context=N`, surrounding lines are returned in `context`, separate from `matches`. Both contain `path`, `line`, and `text`; `total` counts only match entries. ### 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 If `rg` is unavailable, filename search retains a best-effort walk with `fallback="python-walk"` and a note that `.gitignore` is not honored. ``` # 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. --- Source attribution: aden-hive Original project: https://github.com/aden-hive/hive License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: aden-hive Original project: https://github.com/aden-hive/hive Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Development & Engineering Roles: Backend Developer, Data Engineer, DevOps / SRE Specialties: API, Backend Tools: Terminal_Find, Terminal_Rg Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: d368ca428ade8f891706cc24d6aaefa5a61b5451bbe0612362692e3c0944208b