codemap_search_in_files

Search for text within files. Returns line-before, matching line (with exact line/column), and line-after. Supports pagination (5 results per page), filtering by scope (directory/file), and metadata enrichment via include parameter.

searchgrepcontenttext

Parameters

Name	Type	Required	Description
`query`	`string`	✅ Required	Search query string
`useRegex`	`boolean`	❌ Optional	Treat query as regex pattern (default: false)
`include`	`string`	❌ Optional	Comma-separated metadata filters: 'files', 'symbols', 'annotations' (default: 'files')
`scope`	`string`	❌ Optional	Narrow search to specific directory or file path
`symbolKind`	`string`	❌ Optional	Filter by symbol kind: 'function', 'class', 'interface', etc.
`page`	`number`	❌ Optional	Page number for pagination (default: 1, 5 results per page)
`caseSensitive`	`boolean`	❌ Optional	Case-sensitive search (default: false)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_search_in_files",
  "arguments": {
    "query": "TODO"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "results": [
    {
      "file": "src/utils/helpers.ts",
      "line": 45,
      "column": 3,
      "lineBefore": "function processData() {",
      "matchingLine": "  // TODO: Add validation",
      "lineAfter": "  return data;"
    }
  ],
  "totalMatches": 1,
  "page": 1,
  "pageSize": 5
}

ℹ️When to Use This Tool

Find TODOs/FIXMEs
Search for specific text patterns
Locate imports/usage
Find hardcoded values
Grep-style content search

💡Common Patterns

Find TODOs

const todos = await codemap.search.searchInFiles({ query: 'TODO' });

Search in Directory

const apiImports = await codemap.search.searchInFiles({
  query: 'import',
  scope: 'src/api'
});

Regex Patterns

const functions = await codemap.search.searchInFiles({
  query: 'function \\w+\\(',
  useRegex: true
});

💡Pro Tips

Use context lines - lineBefore/lineAfter provide context
Scope searches - Limit to directories for faster results
Regex for patterns - Use regex for complex searches
Paginate large results - Results limited to 5 per page

✅Best Practices

Start simple - Plain text before regex
Narrow scope - Use scope to limit search area
Check page count - May need multiple pages for all results
Case sensitivity - Consider caseSensitive for exact matches

⚠️Common Mistakes

❌ Mistake: Not paginating large results

const results = await codemap.search.searchInFiles({ query: 'import' });
// Only gets first 5 results

✅ Instead: Paginate through all

let page = 1, allResults = [];
do {
  const results = await codemap.search.searchInFiles({ query: 'import', page });
  allResults.push(...results.results);
  page++;
} while (results.results.length === results.pageSize);

Changelog

1 release

- 🆕AddedNew categories, categoryMaxResults, and summary parameters — same category-search and landscape-scan support as codemap_search
- 🆕AddedRelevancy-based sorting — file matches are now sorted by RelevanceScorer score before pagination, with line number as tiebreaker within each file
- 🆕AddedSummary search scoring — file summaries participate in match ranking (0.6× relevance for summary-only matches)
- 🆕AddedAgent-mode insights — agentSummary, per-category insight, and drillDown fields added to responses when the MCP server has agentMode: true