| 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
