tools:
get-directory-tree:
description: |
Generate a directory tree with standard exclusions and gitignore support
Examples:
- get_directory_tree(directory="/path/to/project") # basic usage with default exclusions
- get_directory_tree(directory="/path/to/project", format_args="-L 3") # limit depth to 3 levels
- get_directory_tree(directory="/home/user/code", custom_excludes="dist|build", format_args="-C --dirsfirst") # multiple custom exclusions with colorized output and directories first
- get_directory_tree(directory="/path/to/project", custom_excludes="target") # single custom exclusion
execution:
command: >-
tree '<<directory>>'
-a --gitignore
-I ".git|.claude|.env|.venv|env|node_modules|__pycache__|.DS_Store|*.pyc"
-I "<<custom_excludes>>"
<<format_args>>
parameters:
directory:
description: Directory to generate tree for (quotes are handled automatically in the command)
required: true
custom_excludes:
description: Additional patterns to exclude. Use pipe-separated values for multiple exclusions (e.g., "build|dist|target" or just "build" for single exclusion). Probably not needed if there is a .gitignore file.
required: false
format_args:
description: Additional tree command options (e.g., "-L 3 -C --dirsfirst")
required: false
find-files:
description: |
Locate files by name, pattern, type, size, date, or other criteria with gitignore support
Examples:
- find_files(directory="/full/path/src", arguments="-name *.py") # find all Python files
- find_files(directory="/full/path/project", arguments="-mtime -7") # find files modified in the last 7 days
- find_files(directory="/full/path/data", arguments="-size +1M") # find files larger than 1 MB
- find_files(directory="/full/path/src", arguments="-name *.js", exclude_paths="./build/*|./dist/*") # find JS files excluding build directories
- find_files(directory="/full/path/project", exclude_files="*.log|*.tmp|*.bak") # find all files except logs and temp files
- find_files(directory="/full/path/src", arguments="-name *.py", exclude_paths="*/test/*|*/tests/*", exclude_files="*_backup.py") # find Python files excluding test dirs and backup files
execution:
command: >-
if [ ! -d '<<directory>>' ]; then
echo "Directory does not exist: <<directory>>";
else
cd '<<directory>>' &&
{
echo "find . -type f";
echo "-not -path './.git/*'";
echo "-not -path './.claude/*'";
echo "-not -path './.env/*'";
echo "-not -path './.venv/*'";
echo "-not -path './env/*'";
echo "-not -path './node_modules/*'";
echo "-not -path './__pycache__/*'";
echo "-not -name '.DS_Store'";
echo "-not -name '*.pyc'";
if [ -f .gitignore ]; then
while IFS= read -r line || [ -n "$line" ]; do
[ -z "$line" ] && continue;
case "$line" in '#'*) continue ;; esac;
line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//');
[ -z "$line" ] && continue;
case "$line" in
*/) echo "-not -path './$line*'" ;;
*/*) echo "-not -path './$line'" ;;
*) echo "-not -name '$line'" ;;
esac;
done < .gitignore;
fi;
if [ -n "<<exclude_paths>>" ]; then
echo "<<exclude_paths>>" | tr '|' '\n' | while read -r path; do
[ -n "$path" ] && echo "-not -path '$path'";
done;
fi;
if [ -n "<<exclude_files>>" ]; then
echo "<<exclude_files>>" | tr '|' '\n' | while read -r file; do
[ -n "$file" ] && echo "-not -name '$file'";
done;
fi;
echo "<<arguments>>";
} | tr '\n' ' ' | xargs find | sort;
fi
parameters:
directory:
description: Directory to search in (quotes are handled automatically in the command)
required: true
arguments:
description: Additional find criteria and options (e.g., "-name *.py -mtime -7 -size +1M"). These are appended to the find command after all exclusions.
required: false
exclude_paths:
description: Additional path patterns to exclude, pipe-separated (e.g., "./build/*|./dist/*|./target/*")
required: false
exclude_files:
description: Additional file patterns to exclude, pipe-separated (e.g., "*.log|*.tmp|*.bak")
required: false
find-text-patterns:
description: |
Find text patterns in files with optional context and filtering (via grep)
This tool is useful for searching through code files, logs, or any text files.
Examples:
- find_text_patterns(pattern="function", directory="/full/path/directory", arguments="--include=*.js") # find "function" in JS files
- find_text_patterns(pattern="TODO:", directory="/full/path/src", arguments="-i --include=*.py --include=*.js -B 2 -A 2") # find TODOs case-insensitively with 2 lines of context before and after
- find_text_patterns(pattern="import.*pandas", directory="/full/path/src", arguments="--include=*.py") # find pandas imports in Python files
- find_text_patterns(pattern="error", directory="/full/path/logs", arguments="-i -A 5", exclude_paths="build|dist") # find errors with path exclusions
- find_text_patterns(pattern="debug", directory="/full/path/src", exclude_files="*.log|*.tmp") # exclude specific file types
Output Example:
/full/path/src/script.py:10: import pandas as pd
/full/path/src/script.py:20: # TODO: Refactor this function
/full/path/src/script.py:30: # TODO: Add error handling
execution:
command: >-
if [ ! -d '<<directory>>' ]; then
echo "Directory does not exist: <<directory>>";
else
cd '<<directory>>' &&
grep -r -n --color=never <<arguments>> '<<pattern>>' .
--exclude-dir=.git
--exclude-dir=.claude
--exclude-dir=.env
--exclude-dir=.venv
--exclude-dir=env
--exclude-dir=node_modules
--exclude-dir=__pycache__
$(if [ -n '<<exclude_paths>>' ]; then
echo '<<exclude_paths>>' | sed 's/|/ --exclude-dir=/g' | sed 's/^/--exclude-dir=/';
fi)
$(if [ -n '<<exclude_files>>' ]; then
echo '<<exclude_files>>' | sed 's/|/ --exclude=/g' | sed 's/^/--exclude=/';
fi);
fi
parameters:
pattern:
description: Text pattern to search for (supports regex, quotes are handled automatically in the command)
required: true
directory:
description: Directory to search in (quotes are handled automatically in the command)
required: true
arguments:
description: Additional grep options (e.g., "-i" for case-insensitive, "-A 3 -B 2" for context lines, "--include=*.py" for file filtering). These are placed before the pattern in the grep command.
required: false
exclude_paths:
description: Additional directory patterns to exclude, pipe-separated (e.g., "build|dist|target")
required: false
exclude_files:
description: Additional file patterns to exclude, pipe-separated (e.g., "*.log|*.tmp|*.bak")
required: false
extract-file-text:
description: |
Display contents of a file with line numbers and optional post-processing filters
Note: The arguments parameter is for pipe operations only (post-processing), not cat options.
Examples:
- extract_file_text(file="/path/to/script.py") # view entire file with line numbers
- extract_file_text(file="/path/to/script.py", arguments="| sed -n '10,20p'") # view only lines 10-20
- extract_file_text(file="/path/to/config.json", arguments="| python3 -m json.tool") # pretty-print JSON file
- extract_file_text(file="/path/to/error.log", arguments="| grep ERROR") # filter file to show only ERROR lines
- extract_file_text(file="/path/to/data.txt", arguments="| head -20") # show first 20 lines
- extract_file_text(file="/path/to/log.txt", arguments="| tail -50 | grep WARN") # show last 50 lines, then filter warnings
Output Example:
1 def main():
2 print('Hello world')
3
4 if __name__ == '__main__':
5 main()
execution:
command: >-
cat '<<file>>' <<arguments>> | nl -ba
parameters:
file:
description: Path to the file to display (quotes are handled automatically in the command)
required: true
arguments:
description: Post-processing pipe operations only (e.g., "| sed -n '10,20p'" to show specific line range, "| python3 -m json.tool" to format JSON, "| grep ERROR" to filter lines). Do NOT use for cat options like -n or -b.
required: false
extract-code-info:
description: |
Analyze code files to extract key components like functions, classes, imports, and TODOs.
This tool scans specified files for code elements and returns a structured report showing
where each element is defined (with line numbers). It's useful for quickly understanding
the structure of unfamiliar code without having to read entire files.
Examples:
- extract_code_info(files="/path/to/script.py", types="functions") # list functions in one file
- extract_code_info(files="src/*.py", types="functions,classes") # list functions and classes in src directory
- extract_code_info(files="*.js", types="imports,todos", exclude_paths="node_modules|build|dist") # JS files excluding common directories
- extract_code_info(files="**/*.py", types="functions", exclude_paths="venv|.venv|__pycache__", exclude_files="*_test.py") # Python files excluding tests and virtual envs
execution:
command: >-
for file in $(find <<files>> -type f
-not -path "*/.git/*"
-not -path "*/.claude/*"
-not -path "*/.env/*"
-not -path "*/.venv/*"
-not -path "*/env/*"
-not -path "*/node_modules/*"
-not -path "*/__pycache__/*"
-not -name ".DS_Store"
$(if [ -n "<<exclude_paths>>" ]; then
echo "<<exclude_paths>>" | tr '|' '\n' | while read -r path; do
[ -n "$path" ] && echo "-not -path \"*/$path/*\"";
done;
fi)
$(if [ -n "<<exclude_files>>" ]; then
echo "<<exclude_files>>" | tr '|' '\n' | while read -r file; do
[ -n "$file" ] && echo "-not -name \"$file\"";
done;
fi) 2>/dev/null); do
if [ ! -f "$file" ]; then continue; fi;
echo "=== File: $file ===";
if echo "<<types>>" | grep -q "functions"; then echo "--- functions ---"; (grep -n "^[ ]*def " "$file" 2>/dev/null || grep -n "function " "$file" 2>/dev/null || echo "No function definitions found"); fi;
if echo "<<types>>" | grep -q "imports"; then echo "--- imports ---"; (grep -n "^[ ]*import " "$file" 2>/dev/null; grep -n "^[ ]*from " "$file" 2>/dev/null; grep -n "require(" "$file" 2>/dev/null) | sort -n || echo "No imports found"; fi;
if echo "<<types>>" | grep -q "classes"; then echo "--- classes ---"; grep -n "^[ ]*class " "$file" 2>/dev/null || echo "No classes found"; fi;
if echo "<<types>>" | grep -q "todos"; then echo "--- todos ---"; grep -n -i "TODO\|FIXME" "$file" 2>/dev/null || echo "No TODOs found"; fi;
echo "";
done
parameters:
files:
description: File pattern to analyze (e.g., "*.py", "src/*.js", "/path/to/file.py")
required: true
types:
description: Comma-separated list of information types to extract (functions, classes, imports, todos)
required: true
exclude_paths:
description: Additional directory patterns to exclude, pipe-separated (e.g., "build|dist|target")
required: false
exclude_files:
description: Additional file patterns to exclude, pipe-separated (e.g., "*_test.py|*_backup.py")
required: false
web-scraper:
description: |
Fetch a webpage and convert it to clean, readable text using lynx
Examples:
- web_scraper(url="https://example.com") # get basic text content
- web_scraper(url="https://docs.astral.sh/uv", dump_options="-width=100") # wider output format
- web_scraper(url="https://news.site.com", dump_options="-nolist") # without link list
- web_scraper(url="https://api.site.com/data.json", dump_options="-source") # get source instead of rendered text
execution:
command: >-
lynx -dump -nomargins -hiddenlinks=ignore <<dump_options>> '<<url>>'
parameters:
url:
description: Full URL of the webpage to fetch and convert to text (must include http:// or https://)
required: true
dump_options:
description: Additional lynx options (e.g., -width=100, -nolist, -source)
required: false
