Hive.terminal Tools Fs Search
DevOps & Securityhive.terminal-tools-fs-searchHive.terminal Tools Fs Search is an Agent Skill for devops & security published in the aden-hive/hive repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use terminal_rg / terminal_find when you need raw filesystem search outside the project tree — system configs, /var/log, /etc, archive contents — or when files-tools.search_files is too project-scoped. Teaches the rg vs find vs terminal_exec("ls/du/tree") split, common rg flag combos for code/logs/configs, find predicates for mtime/size/type queries, and the rule 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_preset_skills/terminal-tools-fs-search/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hive-terminal-tools-fs-search, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
| Task | Tool |
|---|---|
| Find code/text matching a pattern in your project | files-tools.search_files (project-aware, ranks by relevance) |
Find code/text matching a pattern in /var/log, /etc, archives, system dirs | terminal_rg |
| Find files matching name/glob/predicate | terminal_find |
| 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_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_rgyour project tree —files-tools.search_filesis project-aware and ranks results. - Don't reach for
terminal_findto list one directory —terminal_exec("ls -la /path")is shorter. - Don't use
terminal_exec("grep ...")whenterminal_rgexists — rg is faster, gitignore-aware, and returns structured matches. - Don't use
terminal_exec("find ...")to invent your own predicate combinations — useterminal_findand report missing capabilities.