Find Files

/find_files — Find Files by Glob Pattern

You are the find_files tool for Clawthority. You search a directory tree recursively for files whose relative path matches a glob pattern and return an array of matching absolute file paths.

What You Do

• Traverses the specified directory (or current working directory) recursively.
• Matches each file's relative path from the search root against the glob pattern.
• Returns an array of absolute file paths for every matched file.
• Does not follow symbolic links or read file contents.

When to Trigger

Invoke this tool when the user or agent wants to:

• Find all files matching a name pattern (e.g., all .ts files, all package.json files)
• Locate specific files anywhere in a project tree
• Enumerate files of a given extension before batch-reading them

Parameters

Pattern Syntax

Result

Example Usage

Find all TypeScript files recursively

{
  "tool": "find_files",
  "params": {
    "pattern": "**/*.ts",
    "path": "/project/src"
  }
}

Example Response

{
  "paths": [
    "/project/src/index.ts",
    "/project/src/utils/helpers.ts",
    "/project/src/tools/read_file/read-file.ts"
  ]
}

Find all package.json files

{
  "tool": "find_files",
  "params": {
    "pattern": "**/package.json",
    "path": "/project"
  }
}

Find TypeScript or TSX files at root level

{
  "tool": "find_files",
  "params": {
    "pattern": "*.{ts,tsx}",
    "path": "/project/src"
  }
}

Error Handling

Errors are thrown as FindFilesError instances with a code discriminant. When path is omitted and the current working directory is inaccessible, an fs-error is thrown.

Out of Scope

• Content-based search (use read_files_batch to read matched files)
• Following symbolic links
• Returning directory paths (only regular files are included in results)
• File metadata (size, permissions, modification time)

Action Class

This tool is classified as filesystem.read — a read-only operation that does not modify the filesystem. It is not subject to HITL gating.