search context 5 min

include_neighbors: When to Use Focused vs Expanded Search

Control how much dependency context comes back with your search results.

🎧
Listen to this guide 2 min
Download MP3

What include_neighbors Does

search_code(query, include_neighbors=True) augments the direct search results with the files that import or are imported by those results. This gives you the full dependency neighborhood — functions in adjacent files, type definitions from shared modules.

When include_neighbors=False (the default), you get only the exact matches. Faster, less tokens, more precise.

The Decision: Focused vs Expanded

Focused (include_neighbors=False)

  • You know exactly what you're looking for
  • Your query is about a specific function or class
  • You're working within one module and don't need cross-file context
  • You're constrained on token budget or response time

Expanded (include_neighbors=True)

  • You're understanding how a system works end-to-end
  • You're planning a change and need to know what else might break
  • You're exploring an unfamiliar area of the codebase
  • Your AI is giving incomplete answers because it's missing dependency context

Focused Mode Example

# You know you're looking for the payment processing function
search_code("process_payment function signature", include_neighbors=False)
# Returns: src/payments.py with the function definition
# Doesn't include: all the files that call it

Good for: editing a specific function, understanding what a function does, quick lookups.

Expanded Mode Example

# You're planning to change the payment flow and need full context
search_code("payment processing flow", include_neighbors=True)
# Returns: src/payments.py + src/webhooks.py (imports payments)
#          + src/models.py (imported by payments)

Good for: impact analysis before a change, understanding system behavior, debugging cross-file issues.

Insight include_neighbors=True typically returns 2-4x more files. For a focused edit, this is noise. For architecture understanding, it's essential.

Combining with graph_impact

When include_neighbors=True isn't enough and you need to understand the full blast radius of a change, use graph_impact() directly:

# What breaks if I change src/auth.py?
graph_impact("src/auth.py", max_depth=3)
# Returns a list of all files transitively affected, up to 3 hops away

Use graph_impact for pre-refactor planning. Use include_neighbors=True for routine context expansion.

Cross-file Signature Visibility

When neighbors are included, Pyckle also includes function signatures from imported files — not just file paths. So if payments.py imports validate_session from auth.py, you'll see the signature of validate_session in the results even if auth.py didn't match the query semantically.

Tip This is particularly useful when your AI is generating code that calls functions from other modules — it can see the exact function signatures without you manually adding those files.

Quick Reference Table

Scenario Recommended setting
Find a specific function include_neighbors=False
Understand a module include_neighbors=False
Plan a refactor include_neighbors=True
Debug cross-file bug include_neighbors=True
Generate code that calls other modules include_neighbors=True
Token-constrained context window include_neighbors=False

What's Next

Connect GitHub Webhooks
Add issues and PRs to your search results
->
All Features
Full feature list including graph_impact and AST parsing
->
← Back to Docs