find

[symbols]

Searches files, content, declarations, code patterns, or semantic meaning within a repository.

Parameters

Examples

Replace sample paths and symbol keys with values from your workspace.

Compact literal content search

{
  "query": "fn invalidate_cache",
  "target": "content",
  "match": "literal"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "fn invalidate_cache",
      "target": "content",
      "match": "literal"
    }
  }
}

{
  "root": "/repo",
  "complete": true,
  "matches": [
    {
      "path": "src/cache.rs",
      "line": 42,
      "text": "fn invalidate_cache() {"
    }
  ]
}

Fuzzy file and identifier hop (ranked)

{
  "query": "usrctrl"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "usrctrl"
    }
  }
}

Exhaustive regex over content

{
  "query": "/fn handle_\\w+/",
  "target": "content"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "/fn handle_\\w+/",
      "target": "content"
    }
  }
}

Exhaustive word match scoped by globs

{
  "query": "timeout",
  "target": "content",
  "match": "word",
  "scope": {
    "globs": [
      "src/**",
      "!**/tests/**"
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "timeout",
      "target": "content",
      "match": "word",
      "scope": {
        "globs": [
          "src/**",
          "!**/tests/**"
        ]
      }
    }
  }
}

Forced literal phrase

{
  "query": "\"exact phrase\""
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find",
    "arguments": {
      "query": "\"exact phrase\""
    }
  }
}

Response Notes

Strict modes scan exhaustively; fuzzy and semantic results are ranked. Complete initial misses explain that ignore rules exclude files, including worktrees under ignored paths. Both response formats retain this hint and the searched root. Use load only if another checkout was intended. Compact responses report automatic routes and changes to the requested mode. Read the scout://guide MCP resource for grammar coverage, examples, and recovery.

Compact search returns root, complete, and matches with path, line, and text. Empty scopes retain zero coverage counts; partial scans retain coverage and recovery. complete describes exhaustive coverage; reason: ranked identifies ranked results.

next supplies replacement arguments for the same query and scope. A changed pageIdentity requires a restart without skip. Live scan identities fingerprint the content each scan reads. Disk edits change them before watcher delivery. Semantic identities track ranking changes. Strict scan resumes verify the earlier prefix with a separate budget equal to limits.find-budget-ms. A changed prefix or an exhausted verification budget requires a restart. An omitted column means 1; responseDetail: full retains the original envelope, timing, language tags, and spans.

Fuzzy pages use continuationToken to retain one ranking after file edits. The fuzzy content candidate scan shares one budget across backend pages. Its default is three seconds. Process options --parse-cap, --take-max, and --load override the configuration that supplies process policy. Overrides remain active after root changes and unload. Restart Scout to change them. Restart Scout with --find-budget to override it; 0 disables the deadline. The cache holds at most 32 snapshots and 32 MiB of serialized results. Snapshots expire after two minutes. Expiry, eviction, and reload require a restart without the token.

Incomplete fuzzy results withhold next. Retry without skip after the index is ready. Failed semantic queries report unavailable with recovery guidance. Read scout://guide for continuation rules, identity requirements, and recovery.

Unreleased multi-root support: scope.rootIds selects loaded roots. Omission selects all. The deepest loaded root owns overlapping files, even when a child root is unselected. Multi-root responses contain root: null, a root table, and rootId on each match. Paths are relative to the owning root. Counts, coverage, ranking, deadlines, and pagination cover the selected union. Explicit semantic search ranks enabled roots semantically. Whole-selection lexical fallback searches every selected root, including disabled roots. If any eligible root is warming, failed, or incompatible, the entire selection uses lexical fallback. Automatic semantic routing requires all selected roots to be enabled, ready, and compatible. Mixed symbol results place native declarations before globally ranked fuzzy fallback candidates. Each lane reserves half the shared candidate horizon.