Reference for the find default tool: find_files, recent_files, and directory_tree.

Find Tool

Script: powers/find.py Dependencies: pydantic

Find files by name, glob pattern, type, modification time, or get a structured directory tree view. Automatically skips common noise directories.

find_files

Find files and directories matching a glob pattern. Returns structured entries with metadata.

Input

Field	Type	Default	Description
`pattern`	`str`	required	Glob pattern to match (e.g., `.py`, `test_.py`, `Dockerfile*`)
`path`	`str`	`"."`	Directory to search in
`max_results`	`int`	`200`	Maximum number of results to return
`include_hidden`	`bool`	`false`	Include hidden files/directories (starting with `.`)
`file_type`	`str`	`"all"`	Filter by type: `"file"`, `"dir"`, or `"all"`

Output

Field	Type	Description
`ok`	`bool`	`true` if search completed
`entries`	`list`	Array of file entry objects (see below)
`total_found`	`int`	Number of entries found
`truncated`	`bool`	`true` if `max_results` was reached
`error`	`str`	Error message on failure

Each entry object:

Field	Type	Description
`path`	`str`	Relative path from search root
`name`	`str`	File or directory name
`type`	`str`	`"file"` or `"dir"`
`size`	`int`	File size in bytes (files only)
`extension`	`str`	File extension (files only)

Examples

// Find all Python files
{"pattern": "*.py", "path": "src"}

// Find test files
{"pattern": "test_*.py"}

// Find YAML files in agents directory
{"pattern": "*.yaml", "path": "agents"}

// Find only Dockerfiles (files only)
{"pattern": "Dockerfile*", "file_type": "file"}

// Find directories named "tests"
{"pattern": "tests", "file_type": "dir"}

// Include hidden files
{"pattern": ".*", "include_hidden": true}

Auto-Skipped Directories

The following directories are always skipped during traversal: __pycache__, node_modules, .git, .venv, venv, .tox, .mypy_cache, .pytest_cache, dist, build, .egg-info, .eggs

recent_files

Find files modified within a recent time window. Results are sorted by modification time (most recent first).

Input

Field	Type	Default	Description
`path`	`str`	`"."`	Directory to search in
`minutes`	`int`	`60`	Find files modified within this many minutes
`glob`	`str`	`"*"`	File glob filter (e.g., `*.py`)
`max_results`	`int`	`50`	Maximum number of results

Output

Field	Type	Description
`ok`	`bool`	`true` if search completed
`entries`	`list`	Array of recent file entries (see below)
`total_found`	`int`	Number of files found
`error`	`str`	Error message on failure

Each entry:

Field	Type	Description
`path`	`str`	Relative path
`name`	`str`	File name
`size`	`int`	File size in bytes
`modified_seconds_ago`	`int`	Seconds since last modification
`extension`	`str`	File extension

Examples

// Files modified in the last 30 minutes
{"minutes": 30, "glob": "*.py"}

// Recently changed files in src/
{"path": "src", "minutes": 10}

// All files changed today
{"minutes": 1440}

directory_tree

Get a structured directory tree view. Returns a nested tree structure showing the project layout.

Input

Field	Type	Default	Description
`path`	`str`	`"."`	Directory to show tree for
`max_depth`	`int`	`3`	Maximum depth to traverse (1-10)
`include_hidden`	`bool`	`false`	Include hidden files/directories
`include_files`	`bool`	`true`	Include files (set `false` for dirs only)

Output

Field	Type	Description
`ok`	`bool`	`true` if tree was built
`tree`	`object`	Nested tree structure (see below)
`total_files`	`int`	Total files in the tree
`total_dirs`	`int`	Total directories in the tree
`error`	`str`	Error message on failure

Each tree node:

Field	Type	Description
`name`	`str`	Name of the file or directory
`type`	`str`	`"file"` or `"dir"`
`children`	`list`	Child nodes (directories only)
`size`	`int`	File size in bytes (files only)

Examples

// Project overview (default depth 3)
{"path": ".", "max_depth": 2}

// Deep dive into source tree
{"path": "src", "max_depth": 4, "include_files": true}

// Directory structure only
{"path": ".", "max_depth": 3, "include_files": false}

Tips

Use find_files for locating specific files by name or extension
Use recent_files to see what was recently changed -- useful for understanding recent activity
Use directory_tree to get an overview of project structure before diving into specific files
All three functions skip the same noise directories automatically
Combine find_files with search for a powerful "find the file, then search its contents" workflow

Find Tool

On this page