# `Codex.Tools.FileSearchTool`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/tools/file_search_tool.ex#L1)

Hosted tool for searching files by name pattern and content.

This tool provides local filesystem search capabilities using glob patterns
for file discovery and optional fixed-string content matching.

## Options

Options can be passed during registration or via context:

  * `:base_path` - Base directory for search (default: cwd)
  * `:max_results` - Maximum results to return (default: 100)
  * `:include_hidden` - Include hidden files (default: false)
  * `:case_sensitive` - Case-sensitive matching (default: true)

## Usage

### Direct Invocation

    args = %{"pattern" => "**/*.ex", "base_path" => "/project"}
    {:ok, result} = Codex.Tools.FileSearchTool.invoke(args, %{})
    # => %{"count" => 42, "files" => [%{"path" => "lib/foo.ex"}, ...]}

### With Content Search

    args = %{
      "pattern" => "**/*.ex",
      "content" => "defmodule",
      "case_sensitive" => false
    }
    {:ok, result} = Codex.Tools.FileSearchTool.invoke(args, %{})
    # => %{"count" => 10, "files" => [%{"path" => "lib/foo.ex", "matches" => [...]}]}

### With Registry

    {:ok, _handle} = Codex.Tools.register(Codex.Tools.FileSearchTool,
      base_path: "/project",
      max_results: 50
    )

    {:ok, result} = Codex.Tools.invoke("file_search", %{"pattern" => "*.ex"}, %{})

## Result Format

Results are returned as a map with:

  * `"count"` - Number of matching files
  * `"files"` - List of file matches, each with:
    * `"path"` - Relative path from base_path
    * `"matches"` - (optional) List of content matches with line numbers

## Pattern Syntax

Uses Elixir's `Path.wildcard/2` for glob patterns:

  * `*` - Matches any characters except path separators
  * `**` - Matches any characters including path separators (recursive)
  * `?` - Matches a single character
  * `[abc]` - Matches any character in the brackets
  * `{a,b}` - Matches either pattern

Examples:
  * `"*.ex"` - All `.ex` files in base directory
  * `"**/*.ex"` - All `.ex` files recursively
  * `"lib/**/*.{ex,exs}"` - All Elixir files under lib/
  * `"test/*_test.exs"` - All test files in test/

---

*Consult [api-reference.md](api-reference.md) for complete listing*