code-search

name	code-search
argument-hint	[symbol or query]
description	Find, trace, or investigate code across local or GitHub repos through the dq index - where a symbol is defined, who references it, an existing pattern to reuse, what changed in recent commits, whether a change is risky, or how data flows upstream/downstream. Returns cited findings (file#Lstart-Lend, commit SHA). For third-party library docs use doc-search; to refresh the index run `dq-scan refresh && dq-sql index`.
when_to_use	Triggers on "where is X defined", "who calls Y", "find an example of Z", "what changed in <file> or <commit>", "is this change safe", "where does this data flow from or to".
metadata	[{"name":"dq index","description":"The dq MCP index is the primary surface - it spans every indexed repo and returns whole symbol bodies with exact file#Lstart-Lend locations. Use it before grepping or reading whole files."},{"name":"dq tools","description":"The dq tools are the MCP shell commands for symbol search, definition, references, and full-text search. They return cited findings and notes on stale sources."},{"author":"magic-man"},{"tags":["code","search","trace","investigate"]}]

Code Search

Find, trace, or investigate code through the dq index - it spans every indexed repo and returns whole symbol bodies with exact file#Lstart-Lend locations. Use it before grepping or reading whole files.

Route: inline for a lookup, subagent for an investigation

A fork costs ~10k tokens of setup; recall is ~6ms. So:

• "Where is X / who calls X", a single trace, a pattern to reuse - call the dq tools inline (below), answer directly.
• A real investigation (tracing a feature across many files, reading many full bodies, auditing a repo or commit range - tens of thousands of tokens of churn) - dispatch Agent(subagent_type "dq-toolkit:code-research", "<what to investigate>"); it works on its own context and returns tight cited findings. Parallel investigations -> one agent each.

The dq tools

For a single "where is X / who calls X", the key calls:

• Trace a symbol in one call (definition(s) + body + references): mcp__plugin_dq-toolkit_dq__explore_symbol(name, site?, max_refs?, context?) - prefer this over chaining goto_definition -> get_record -> find_references; references are capped at max_refs (default 50), full count in total_references
• Go to definition: mcp__plugin_dq-toolkit_dq__goto_definition(name)
• Find references / callers: mcp__plugin_dq-toolkit_dq__find_references(name, site?, context?) - context=True carries each call site's source line in text
• Full-text over symbols/docs: mcp__plugin_dq-toolkit_dq__search_index(query, kind="code", site?, limit?, full?, offset?) - full=True inlines each truncated hit's body; offset pages deeper and total reports the full match count
• Regex, structural, and discovery tools: the full tool table is in references/code-search.md#mcp-tools-agent-surface

Every tool carries a note (and most wrap a results array - search_index also adds total; explore_symbol returns {definitions, references, total_references, note} instead). Relay note to the user when present - it signals a stale source (e.g. "dq index may be stale - foo (47d ago); refresh with dq-scan refresh && dq-sql index").

Call mcp__plugin_dq-toolkit_dq__list_repos() for the indexed repos and their symbol counts; if it returns nothing, the index isn't built - run dq-scan refresh && dq-sql index.

Discipline

• Don't grep or read whole files first: goto_definition/find_references/search_index are faster and complete. Reach for grep_source/ast_query only when symbol search isn't enough.
• The index auto-refreshes for the current repo at SessionStart; run dq-scan refresh && dq-sql index to rebuild. Stale or missing results usually mean a refresh is due.
• dq-sql is the backend engine the MCP shells to, not a surface the agent calls directly.

References

• references/code-search.md - Full MCP tool table, refresh commands, SQLite schema, troubleshooting
• references/investigation.md - Locate/index a target, commit & change analysis, bug/risk hunting, upstream/downstream tracing
• references/architecture.md - Crate roles and data flow, for modifying dq-toolkit internals
• examples/commands.md - Single-symbol tool-call patterns
• examples/investigation.md - Index a target, review commits, trace a data path, find risk