GlobTool: Find Files

GlobTool does exactly what you'd expect: finds files by name or wildcard pattern.
But within Claude Code's main loop, it actually serves as:

Transforming "I roughly know what file I'm looking for" into "I have identified the candidate paths."

With many complex tasks, the first step isn't reading a file directly; it's narrowing down the scope first.
GlobTool is the standard entry point for this step.

tools/GlobTool/GlobTool.ts:

const inputSchema = z.strictObject({
  pattern: z.string().describe('The glob pattern to match files against'),
  path: z.string().optional().describe('The directory to search in'),
})

This schema is simple, but its design intent is clear:

• pattern: used to express "what I'm looking for"
• path: used to limit the search scope

In other words, Claude Code wants the model not to blindly scrape the entire repo by default, but rather to learn how to narrow down the search radius.

These declarations in the source code are particularly worth noting:

isConcurrencySafe() {
  return true
}

isReadOnly() {
  return true
}

isSearchOrReadCommand() {
  return { isSearch: true, isRead: false }
}

This shows the system has defined GlobTool as from the very beginning:

• read-only
• concurrency-safe
• explicitly a "search-type" tool

This matters a great deal for main loop scheduling and UI rendering.

The model knows roughly what filename or extension it's looking for

GlobTool

Returns candidate file paths

FileReadTool continues with detailed reading

FileEditTool / FileWriteTool

GlobTool does not directly expose Bash find to the model; instead, it relies on its own internal file search implementation:

import { glob } from '../../utils/glob.js'

This means:

• structured search results
• permissions-aware
• return values better suited for downstream model processing

This differs most from Bash commands in that:
the system knows "you are performing file discovery," rather than just seeing a block of raw shell output.

There's some very practical logic inside validateInput():

if (path) {
  const absolutePath = expandPath(path)
  ...
  if (!stats.isDirectory()) {
    return {
      result: false,
      message: `Path is not a directory: ${path}`,
    }
  }
}

This shows GlobTool clearly distinguishes between:

• the path is a directory
• the path doesn't exist
• the path is incorrect

It even attempts to suggest paths relative to the working directory.
Details like this make it feel like a true product-facing tool, rather than just an SDK demo.

There's a default limit in the call logic:

const limit = globLimits?.maxResults ?? 100

This shows Claude Code is well aware of one problem:

Without result limiting in file search, it's easy to return hundreds or thousands of items at once, wasting context.

So GlobTool's goal isn't "the more, the better," but rather "provide the main loop with a sufficiently useful set of candidates."

This is the most important point to remember:

• GlobTool: I roughly know what file is named
• GrepTool: I roughly know what text is inside the file

These two tools are often conflated, but from an engineering perspective, they represent two different search strategies.

FileReadTool GlobTool Model FileReadTool GlobTool Model Search for a certain type of file Return candidate paths Read the most relevant files Return body text

Incorrect.
The advantage of GlobTool lies exactly in being structured, controllable, and more amenable to the main loop.

Also incorrect.
It affects permissions checking, context control, and downstream tool selection.

Search tools often look simple, but within a system like Claude Code,
"finding the right file first" is itself a very critical main path.

The value of GlobTool can be summed up in one sentence:

It makes "discovering target files by file path pattern" into a standard, read-only, structured search entry point for Claude Code, serving as the true first step for many tasks.