search_patterns

What It Does

search_patterns scans a codebase for known structural anti-patterns using pre-built detection rules. Each pattern is a combination of regex matching and false-positive exclusion that would take significant effort to replicate with raw grep.

The difference between search_patterns("empty-catch") and rg "catch.*\{\s*\}" is precision. The grep version matches test files, catches with intentional comments explaining why they are empty, and catches that contain logging but span multiple lines. The built-in pattern knows to skip test files, recognizes documented empty catches, and handles multi-line blocks correctly.

Built-in Patterns

Pattern	What it detects	False-positive handling
empty-catch	Catch blocks with no error handling	Skips catches with comments, test files
any-type	TypeScript any usage	Skips type definitions that genuinely need any
console-log	Console statements in production code	Skips test files, debug utilities
await-in-loop	Sequential await inside for/while loops	Skips loops with explicit ordering comments
todo-fixme	TODO/FIXME/HACK comments	Groups by priority keyword
large-function	Functions exceeding line thresholds	Configurable threshold
deep-nesting	Excessive if/else/try nesting	Measures actual depth, not indentation
magic-number	Unnamed numeric literals	Skips common constants (0, 1, -1, 100)
scaffolding	Leftover scaffolding and boilerplate	Detects template markers, placeholder text

Custom Regex

Beyond the built-in patterns, you can pass any regex:

search_patterns(repo, "custom", custom_regex="process\\.env\\.")

Custom patterns get the same output formatting and file-pattern scoping as built-in ones, but without the false-positive exclusion logic.

Why the Token Reduction Is Real

The -88% reduction comes from three sources:

Scoped scanning. Built-in patterns already know which file types to scan. empty-catch only looks at .ts, .tsx, .js, .jsx files. Grep scans everything unless you add --glob manually.

Ranked results. Findings are sorted by severity and grouped by file. The most problematic files appear first. Grep returns matches in directory traversal order.

False-positive exclusion. Each pattern has exclusion rules that prevent matches the agent would have to manually filter. A typical any-type grep returns 200+ results including type definition files and intentional escape hatches. The pattern returns the 30 that actually need attention.

Benchmark Results

Tested on anti-pattern detection across three codebases:

Scenario	search_patterns	rg equivalent
Find empty catches	1 call, 2.5K tokens	2 calls (search + filter tests), 21K tokens
Find console.log in prod	1 call, 1.8K tokens	3 calls (search + exclude tests + exclude utils), 18K tokens

The native workflow requires multiple grep passes: one to find matches, one to exclude test files, often a third to exclude known-safe directories. search_patterns handles all of this in a single call.

When to Use

• During code audits (/code-audit, /review) — scan for structural issues before manual review
• Before releases — check for leftover TODOs, console.log statements, scaffolding
• Onboarding — quickly assess code quality patterns in an unfamiliar codebase
• Refactoring prioritization — find which files have the most anti-patterns

When to Use Something Else

Use search_text when looking for a specific string that is not a structural anti-pattern. search_patterns is for known categories of issues, not arbitrary text search.

Use analyze_complexity when you need quantitative complexity metrics (cyclomatic complexity, function length distributions) rather than specific pattern matches.

Use a dedicated linter (ESLint, Biome) when you need rule enforcement in CI. search_patterns is a discovery tool for AI agents, not a CI gate.