Search & Navigation
Glob, Grep, patterns
How Claude Code finds code in a project
Before editing anything, the agent needs to understand what is actually in the project. Claude Code does this with two complementary search tools: Glob finds files by name and path, while Grep finds text inside files. They answer different questions: Glob answers "where do the relevant files live?" and Grep answers "which files contain this string or regex pattern?" The agent picks the right tool itself and often chains them, so you do not have to walk directories by hand.
The Glob patterns on this page are ordinary glob expressions. **/*.ts means "any .ts file at any nesting depth"; the double star ** expands to any number of subfolders, and braces {js,ts} list alternatives. A leading ! (e.g. !**/node_modules/**) excludes a directory. Glob results come back sorted by modification time, so the most recently touched files float to the top.
Glob and Grep: division of labour
Grep is built on ripgrep (rg), a very fast regex search engine that respects .gitignore and skips binary files. The patterns shown here are typical: function.*async locates async function declarations, TODO|FIXME|HACK collects reminder markers, and console\.log catches debug calls (the dot is escaped to mean a literal dot rather than "any character"). The output_mode controls what comes back: content returns the matching lines, files_with_matches returns only file paths (fastest for an initial sweep), and count returns match counts. The -i flag is case-insensitive, -C 3 adds three lines of context, and glob="*.ts" narrows the search to a file type.
A concrete example
Suppose you ask: "find where useState is used in components." The agent first runs Glob (src/components/**/*.tsx) to scope the set of components, then runs Grep with glob="*.tsx" over useState, returning files with line numbers. Common pitfalls: using a regex where a literal string would do (and the reverse — forgetting to escape special characters such as ., (, {); running Grep with no filter on a project of thousands of files instead of files_with_matches; and forgetting that for an unfamiliar codebase it is better to delegate the search to a sub-agent via Task with the Explore agent, to keep the main context clean.
Glob
Pattern-based file search. Quickly finds files by name, extension, path.
Grep
Content search in files. Supports regex, filters, context.
Glob uses patterns to find files. Results are sorted by modification time:
| Pattern | Description |
|---|---|
**/*.ts | All TypeScript files |
src/**/*.tsx | All TSX files in src/ |
**/test/*.spec.ts | All spec files in test folders |
*.config.{js,ts} | All config files at root |
!**/node_modules/** | Exclude node_modules |
src/components/Button.tsx
src/components/Header.tsx
src/pages/Home.tsx
...
Grep searches text or regex inside files. Built on ripgrep (rg) for speed:
function.*asyncFind async functionsregexTODO|FIXME|HACKFind marker commentsregeximport.*from.*reactFind React importsregexconsole\.logFind debug logsliteralsrc/api.ts:15: // TODO: handle errors
src/utils.ts:88: // TODO: refactor this
Output Modes
content— matching linesfiles_with_matches— file paths onlycount— match counts
Useful Options
-i— case insensitive-C 3— 3 lines of contextglob="*.ts"— file filter
Claude automatically combines Glob and Grep for complex queries:
2. Grep: pattern="useState", glob="*.tsx"
src/components/Form.tsx:8
src/components/Modal.tsx:5
...
Find file by name
GlobPattern: **/auth*
Find function usage
GrepPattern: validateUser
Find class definition
GrepPattern: class UserService
Explore structure
Task + ExplorePattern: Uses sub-agent
Search Tips
- •For exploring unfamiliar codebase, use Task with Explore agent
- •Grep with output_mode="files_with_matches" is faster for initial search
- •Use -C for context around found lines
- •Escape special chars in regex: \{\} for literals
Frequently asked questions
What is the difference between Glob and Grep in Claude Code?
Glob finds files by name and path (e.g. src/**/*.tsx returns all TSX files in src), while Grep searches for text or a regex inside files. Glob answers "where do the relevant files live?" and Grep answers "which files contain this string?" The agent often chains them: Glob scopes the set of files, then Grep searches within them.
How do I search file contents in Claude Code?
Use the Grep tool — it is built on ripgrep (rg) and supports regular expressions. The output_mode controls the format: content returns matching lines, files_with_matches returns only file paths (fastest for an initial sweep), and count returns match counts. The -i flag is case-insensitive, -C 3 adds context lines, and glob="*.ts" narrows the search to a file type.
What does the ** pattern mean in Glob?
The double star ** expands to any number of nested subfolders. For example, **/*.ts matches any .ts file at any depth, and src/**/*.tsx matches all TSX files under src. Braces {js,ts} list alternatives, and a leading ! (!**/node_modules/**) excludes a directory. Glob results are sorted by modification time, so recently changed files appear first.
How does Claude Code explore an unfamiliar project?
For an unfamiliar codebase it is best to delegate the search to a sub-agent via Task with the Explore agent — it gathers the project structure and architecture without cluttering the main context with intermediate results. For pinpoint tasks, Glob (to find files) plus Grep with output_mode="files_with_matches" (to quickly see where a symbol appears) is enough.
This lesson is part of a structured LLM course.
My Learning Path