Grep Tool

The Grep tool searches file contents using regular expressions. It provides fast, feature-rich content search across your entire codebase. Use Grep when you need to find where a function is defined, which files import a module, or where a specific pattern appears.

Parameters

Parameter	Type	Required	Description
`search_pattern`	string	Yes	Regex pattern to search for in file contents
`search_path`	string	No	Directory or file to search within (default: project root)
`output_mode`	string	No	`files_with_matches` (default), `content`, or `count`
`glob`	string	No	Glob pattern to filter which files are searched
`type`	string	No	Filter by language type (js, py, ts, go, etc.)
`-i`	boolean	No	Case-insensitive search
`-n`	boolean	No	Include line numbers (only with `content` mode)
`-B`	number	No	Lines to show before each match
`-A`	number	No	Lines to show after each match
`-C`	number	No	Lines to show before and after each match
`head_limit`	number	No	Maximum number of results
`offset`	number	No	Skip first N results (for pagination)
`multiline`	boolean	No	Enable multiline matching

Output Modes

files_with_matches (default)

Returns only file paths containing matches. Fast and clean — use this to discover which files are relevant, then Read them:

> Which files import the auth module?

Agent invokes Grep:
  search_pattern: from.*auth|require.*auth
  output_mode: files_with_matches

Result:
  src/components/LoginForm.tsx
  src/lib/api.ts
  src/middleware.ts
  src/app/layout.tsx

content

Returns matching lines with surrounding context. Use with -n for line numbers and -A/-B/-C for context:

> Show me the login function with context

Agent invokes Grep:
  search_pattern: export.*function login
  output_mode: content
  -n: true
  -C: 3

Result:
  src/auth/login.ts
    39-
    40-  /**
    41-   * Authenticate user and return tokens
    42:  export async function login(email: string, password: string) {
    43-    const user = await findUserByEmail(email);
    44-    if (!user) {
    45-      throw new AuthenticationError('Invalid credentials');

count

Returns match count per file — useful for understanding how widespread a pattern is:

> How many console.log statements are there?

Agent invokes Grep:
  search_pattern: console\.log
  output_mode: count

Result:
  src/components/Header.tsx: 3
  src/lib/api.ts: 5
  src/app/page.tsx: 2
  ... (12 files, 34 total)

File Filtering

By Glob Pattern

Filter which files are searched using glob patterns:

> Search only in TypeScript files

Agent invokes Grep:
  search_pattern: useEffect
  glob: **/*.{ts,tsx}
  output_mode: files_with_matches

By Language Type

Use the type parameter for predefined language sets:

> Search only in JavaScript/TypeScript files

Agent invokes Grep:
  search_pattern: dangerouslySetInnerHTML
  type: js
  output_mode: content
  -n: true

Available types: js, ts, py, go, rust, java, cpp, css, html, json, md, yaml, and more.

Tip: Using type is more efficient than glob for filtering by language.

Context Lines

Context lines are only available with output_mode: content:

# Show 5 lines before each match (function signature, imports)
search_pattern: handleSubmit
-B: 5
-n: true

# Show 10 lines after each match (function body)
search_pattern: export default function App
-A: 10

# Show 3 lines before and after
search_pattern: TODO
-C: 3

Pattern Syntax

Grep uses a powerful regex syntax:

Pattern	Description
`function\s+\w+`	Function keyword followed by a name
`import.*from\s+['"]react['"]`	React imports
`\bTODO\b`	Word boundary match for "TODO"
`export\s+(const	function
`\.\.\.\w+`	Spread operator usage

Warning: Literal braces in patterns must be escaped. This is important for searching generic TypeScript types: useState<number> needs useState\<number\> as the pattern.

Multiline Search

Enable multiline: true to match patterns spanning multiple lines:

> Find try-catch blocks without error logging

Agent invokes Grep:
  search_pattern: catch\s*\([^)]*\)\s*\{\s*\n\s*throw
  multiline: true
  output_mode: content

Note: Multiline mode is more expensive. Use it only when you need to match across line boundaries.

Pagination

For large result sets, use head_limit and offset together:

# First page
search_pattern: TODO
head_limit: 20
offset: 0

# Second page
search_pattern: TODO
head_limit: 20
offset: 20

Case Sensitivity

Searches are case-sensitive by default. Use -i for case-insensitive matching:

> Find all mentions of "nilux" regardless of case

Agent invokes Grep:
  search_pattern: nilux
  -i: true
  output_mode: files_with_matches

When to Use Grep vs Glob

Use Grep when...	Use Glob when...
Finding content inside files	Finding files by name
Searching for function/variable usage	Locating files by extension
Finding TODO comments	Discovering project structure
Checking where an import is used	Finding config files by name

Often combined: Glob finds candidate files, Grep searches within them, Read examines the results.

Common Patterns

Find function definitions:

search_pattern: function\s+handleSubmit

Find all imports from a module:

search_pattern: from\s+['"]\.\.\/lib\/api['"]

Find error handling:

search_pattern: catch\s*\(

Find deprecated APIs:

search_pattern: @deprecated

Find specific string literals:

search_pattern: 'https://api\.example\.com'

Count test files:

search_pattern: describe\(
glob: **/*.test.*
output_mode: count

Next Steps

Glob — Finding files by name pattern
Read — Reading files found by Grep
Tools Overview — All available tools