Searches the repo for a string or pattern so you can find the right file before you read code.
DESCRIPTION
This is the location tool. It tells you where something lives, not how it works. Use it to find env vars, route names, error messages, feature flags, or scattered call sites before you narrow with read_code.
GOOD FIT
AVOID IT WHEN
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search text or regex pattern. |
| path | string | No | Absolute path to the repo or subdirectory to search. Omit to search the current project. |
PATH PARAMETER
Use the absolute path to the project root on the machine where the code is available. In Cursor, VS Code, or Windsurf that usually means the workspace root you already have open. On a remote dev box, pass the absolute path on that remote machine. If the path does not exist or the service cannot access it, the tool returns an explicit error instead of guessing. Results are best when the folder is a real project root with .git or package.json. Private GitHub repos are not fetched automatically.
SEARCH STRATEGY
Start with the most stable string you have: an env var, endpoint segment, error message, or exported symbol name. If the result set is still wide, narrow with a more exact query and then hand the target file to read_code.
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "find_code", "arguments": { "query": "rate_limit_exceeded", "path": "/Users/name/projects/zephex" } }}dashboard/src/app/docs/api-reference/page.tsx:162 "rate_limit_exceeded"dashboard/src/app/docs/support/billing/page.tsx:74 subsequent tools/call requests return a rate_limit_exceeded errorsrc/middleware/scope-task-rate-limit.ts:41 super("Rate limit exceeded for scope_task")TOKEN EFFICIENCY
Most find_code calls land around 80 to 250 tokens because they return matches, not file bodies. The manual alternative is opening multiple candidate files, which often turns into 5,000 to 20,000 tokens of unnecessary reading.