Description
Code Graph Query Tools let developers and coding agents ask dependency questions against the Dots code knowledge graph from any terminal. dots graph maps five read-only verbs onto the code-graph routes: reverse callers, forward callees, transitive impact, shortest trace, and neighborhood context. Symbol references accept stable human ids or friendly path-qualified names, with strict hop and limit validation.
The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Turns impact analysis into a direct query instead of a manual repository-wide search.
- Supports both forward and reverse dependency exploration around a symbol.
- Finds a shortest call path when developers need to explain how two surfaces connect.
- Uses the same wire contracts as MCP, keeping agent workflows consistent across protocols.
- Rejects malformed bounds before making a request, producing predictable automation failures.
User Story
Before changing a service function, a developer asks for its callers, expands the incoming blast radius two hops, and traces one surprising consumer back to the source. They leave with a bounded set of code symbols to review rather than a speculative file list. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The feature is automatable: packages/cli/src/commands/graph.ts exposes a closed query vocabulary over server routes. Callers can compose the results, but cannot register additional graph algorithms into the CLI. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: Direct caller and callee queries with bounded result counts.
- Capability: Transitive impact analysis, shortest call traces, and immediate graph context.
- Capability: Human-id and path-qualified symbol references with MCP-compatible results.
- Limit: Queries only reflect the last successfully ingested graph snapshot; stale or absent repository data cannot be repaired by these read-only verbs.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/cli/src/commands/graph.tspackages/cli/src/services-factory.tsdocs/cli/mcp-and-repo-commands.md