find_files
Find and list project files and directories scoped to the workspace, respecting .gitignore. Supports glob or regex patterns, type/extension filters, depth limits, sorting, and detail views.
Instructions
Workspace-scoped file/directory finder and directory lister. Unlike shell find/fd/ls, results are confined to the active project (no .git/, node_modules/, build output, or anything else .gitignore excludes), every call is recorded in the project's stats, and the pattern semantics are consistent across hosts. pattern is optional — omit it to list everything. Supports glob and regex patterns, extension and type (file/dir/any) filters, depth limits (max_depth=1 lists one level, like ls), sort_by name/size/modified, and include_details for a per-entry [FILE]/[DIR]/[LINK] marker, size, and modified time.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory to search in (absolute path, file:// URI, or workspace-relative path). Defaults to the workspace root. | |
| type | No | Restrict to files, directories, or both. Default: 'file'. | |
| pattern | No | Glob (or regex if use_regex=true) matched against the file/directory name. When the pattern contains '/' it matches the full relative path. OPTIONAL — omit it to list every entry. A literal "." only matches a file named ".". | |
| sort_by | No | Order of the result list: 'name' (directories first, then path), 'size' (largest first), 'modified' (newest first). Default: name. | |
| extension | No | Filter by file extension, e.g. 'go' or '.go'. | |
| max_depth | No | Maximum directory depth to descend. 1 lists one level only, like ls. Default: unlimited. | |
| use_regex | No | Treat pattern as a regular expression instead of a glob. Default false. | |
| max_results | No | Maximum number of results to return. Default 500. | |
| include_hidden | No | Include hidden files and directories (starting with '.'). Default false. | |
| include_details | No | Render each entry with a [FILE]/[DIR]/[LINK] marker, its size and last-modified time (symlinks as 'name -> target') instead of a bare path list. Default false. |