Learn more about Sourcegraph's agentic Code Search tool Deep Search.
Deep Search is an agentic code search tool that understands natural language questions about your codebase. When a question is submitted, Deep Search performs an in-depth search and returns a detailed answer. The conversation can be continued with follow-up questions to dive deeper into relevant code. Under the hood, Deep Search is an AI agent that uses various tools to generate its answer. The tools are functionalities available in Sourcegraph. They include multiple modes of Sourcegraph's Code Search and Code Navigation features. All processing happens within your Sourcegraph instance. Only external calls are made to the configured LLM. The core of Deep Search is an agentic loop. The AI agent can intelligently use tools to explore the codebase. In each loop iteration, the agent gradually refines its understanding of the question and codebase, searching until it is confident in its answer. Every Deep Search response includes a detailed list of sources contributing to the answer. These sources show exactly which searches were performed and which files were read. The list of sources is extremely useful for understanding where the answer came from and for further explorations of the codebase. The answer is formatted in Markdown and can include links to relevant files, directories, or repositories. If prompted to do so, Deep Search can also generate diagrams as part of its answer. ## Best practices - Give the agent a starting point for the search: use @-mentions to mention relevant repositories or files. The more specific you are, the faster the search will be. - Provide reasonably scoped questions. The agent will perform much better if it does not have to read the entire codebase at once. - Check the list of sources. This is extremely useful for debugging and understanding where the answer came from. Ask a follow-up question and mention the missing source if something is missing. ## Using search contexts You can reuse the same [search contexts](/code-search/working/search-contexts) you already use in Code Search when creating a new Deep Search query. Click **Set scope** in the composer to select a search context and limit Deep Search to that repository scope. Deep Search automatically pre-selects your default search context. Search contexts are useful when you want to keep Deep Search focused on a specific part of your codebase, such as a team's repositories, a product area, or another shared scope used across your organization. Limiting Deep Search to a smaller set of repositories can help it search faster and produce more focused, higher-quality answers. To learn how to create and manage search contexts, see [Search contexts](/code-search/working/search-contexts). ## Using @-mentions Type `@` at any point while entering a query to add context. By default, the menu shows repositories relevant to you based on your commit history. As you type, suggestions update in real-time to show matching files and repositories. The search is keyword-based and supports spaces. For example, typing `@internal search.go` finds files named `search.go` within `internal` folders. To narrow results to a specific directory, include the directory name in your query. You can @-mention: - **Repositories** — scope the search to specific repos - **Files** — point the agent to particular files ## Using Evaluator Evaluator lets Deep Search write and run Lua scripts over Sourcegraph search results. Deep Search decides when to use Evaluator and writes the script automatically; you do not need to write or run code yourself. Evaluator is useful when answering a question that requires more than reading a small set of search results. For example, a script can run several searches, inspect candidate files, join results by repository or path, deduplicate findings, calculate counts, and produce a structured report. The intermediate results are processed by the script rather than added to the LLM's context window. Deep Search receives the aggregated result, its supporting sources, and links to any generated files. ### How it works Evaluator runs Lua in a sandboxed runtime within Sourcegraph: 1. Deep Search generates a script based on your question. 2. The script calls Sourcegraph's existing keyword, regular expression, repository, commit, and diff search APIs. 3. Results are streamed back to the sandbox so the script can filter and aggregate them without returning every match to the LLM. 4. The script returns a compact result to Deep Search or it can write a durable CSV, JSON, or SVG file for larger outputs. 5. Deep Search summarizes the findings and links to the generated files and supporting sources. ### Security and guardrails Evaluator runs scripts generated by Deep Search; it does not execute code from your repositories. The sandbox applies the following controls: - It has no direct network, system, or general filesystem access. - Scripts can only use modules provided by Sourcegraph for search, source file reads, formatting, and generated file outputs. - Search and source file operations are read-only and use Sourcegraph's existing APIs and repository permissions. Searches also use the search context selected for the conversation. Evaluator cannot modify repositories. - The generated file module can only write bounded output files managed by Sourcegraph. It does not provide access to the Sourcegraph host filesystem. - Intermediate search results are processed inside the sandbox. Only the script's return value, supporting sources, and generated file metadata are returned to Deep Search and added to the LLM context. ### When Evaluator helps Evaluator provides the most value when a task requires exhaustive collection or programmatic comparison across many results: - **Inventories and audits** — map every API route to its owning service, inventory dependencies across repositories, or identify repositories using a vulnerable package version. - **Migration planning** — produce a CSV or JSON checklist of services that still use an old package, API, or configuration and have not adopted its replacement. - **Cross-referencing** — compare the results of multiple searches, such as files that match one implementation pattern but not another. - **Aggregation and reporting** — group findings by repository, language, team, or dependency and calculate totals without pasting every row into the answer. Evaluator enables larger, structured analyses when the result set or computation would otherwise be too large or complex to handle reliably in the model's context window. Example prompts that benefit from Evaluator include: - Create a CSV of every API route and the service that handles it. Include the repository, file, line number, route, and owning service. - Across all repositories, create a CSV of services still using Log4j versions earlier than 2.17. Group the results by repository and detected version. - Create a migration checklist of every service that imports `old/package` but does not yet import `new/package`. ## Examples of prompts - Find examples of logger usage and show examples of the different types of logging we use. - I want to know when the indexing queue functionality was last changed in `@zoekt`. Show me the last few commit diffs touching this code and explain the changes. - Look at the GraphQL APIs available in `@sourcegraph/sourcegraph`. Are any of them unused? The client code is in the `@cody` repository. - Which tools do we use in our build processes defined in `BUILD.bazel` files? - Generate a request flow diagram for `src/backend`. Mark the auth and rate limit points. - Based on the findings in `https://sourcegraph.com/deepsearch/e3c0150a-b7ef-4955-bed4-d5820ca7a70d`, investigate whether the same logging patterns appear in our other microservices. - Which packages in `@myorg/repo` still import pkg/errors but haven’t migrated to `corp.pkg/logging/v2`? ## Conversation sharing