codegraph

Measures code complexity metrics for refactoring decisions. USE WHEN: identifying functions that need simplification, reviewing code quality, or prioritizing technical debt. Returns cyclomatic complexity score per function, with name, line range, and file path. Scores >10 typically indicate refactoring candidates, >20 is high complexity. Use threshold to filter — only functions at or above the threshold are returned. Omit line to analyze all functions in a file. Returns: {functions:[{name, complexity, grade, node_id, line_start, line_end, details:{complexity_branches, complexity_loops, complexity_logical_ops, complexity_nesting, complexity_exceptions, complexity_early_returns, lines_of_code}}], summary:{total_functions, average_complexity, max_complexity, above_threshold, threshold, overall_grade}, recommendations:[]} Requires uri parameter. Optionally line for a specific function.

Predicts blast radius of code changes before making them. USE WHEN: planning refactoring, renaming symbols, deleting code, or assessing risk. Returns: direct impacts (callers, references, subclasses), indirect impacts (2-level transitive), and CROSS-PROJECT impacts (consumers in other indexed projects found via unresolved calls, type references, and #include tracking). Risk level is elevated when cross-project consumers exist. changeType affects analysis: 'modify' shows callers/dependents, 'delete' shows all references that would break, 'rename' shows all sites needing updates. Requires uri and line parameters.

Find things described in an indexed design doc that don't exist in the code yet. Extracts backtick-wrapped identifiers from the doc and returns ONLY those not found in the code graph. Each gap includes the heading-path context showing which section of the doc describes the missing item. USE WHEN: checking what's left to implement from a design doc, or building a TODO list from an architecture spec.

Finds all files importing a specific module or package. USE WHEN: planning library migrations, finding all React component usages, or discovering internal module consumers. Pass the module name via `moduleName` param (e.g., 'vscode', 'lodash', 'react', './utils'). Returns array of files that import the specified module, with file path and import details. matchMode controls matching: 'exact' for full name, 'prefix' for starts-with, 'contains' for substring, 'fuzzy' for approximate matching.

Finds functions matching signature patterns. USE WHEN: searching by structural characteristics rather than names - parameter count, return types, or modifiers. namePattern supports wildcards: 'get*' matches getUser, getData; '*Handler' matches requestHandler. paramCount filters by exact count; use minParams/maxParams for ranges. returnType matches against the function's return type string. modifiers filters by async, static, public, private, etc.

Detect circular import/dependency chains in the codebase. USE WHEN: auditing architecture health, finding import cycles that prevent tree-shaking or module splitting, or diagnosing build/bundler errors caused by circular references. Returns each cycle as an ordered list of file paths with the originating file repeated at the end (e.g. ["a.rs", "b.rs", "a.rs"]). Self-imports are also detected. Use max_cycle_length to cap large cycles. Use compact=true for a quick yes/no answer with counts only.

Find unused imports — modules imported but never referenced by any function in the importing file. USE WHEN: cleaning up import lists, reducing bundle size, or auditing a file before refactoring. Returns dead_imports (confirmed unused, module is in the graph), unresolved_imports (external/third-party modules that could not be verified), total_imports, and dead_count. Provide uri to restrict to one file; omit for a workspace-wide scan. LIMITATIONS: macro-generated call sites and dynamic dispatch may cause false positives.

Discovers application entry points and execution starting points. USE WHEN: understanding app architecture, tracing request flow, or finding where to start debugging. START HERE when exploring unfamiliar backend applications. Returns array of entry points with name, kind, file path, line range, and signature. Default returns architectural entry points only (main, HTTP handlers, CLI commands, event handlers). Use entryType='all' to include tests and public API, or 'test'/'public' for those specifically. Default limit 50. Use compact=true for minimal output.

Find the most-called functions in the codebase, ranked by caller count. USE WHEN: identifying performance bottlenecks, understanding which functions are central to your codebase, or deciding where to focus optimisation or review effort. Scores each function by incoming Calls edges: direct callers count 1.0, depth-2 callers 0.5, depth-3 callers 0.25. Returns an array of functions with name, file path, line range, direct_callers, transitive_callers, score, and signature. Default limit 20.

Find all functions registered as implementations of an ops struct field (e.g., who implements ndo_open in net_device_ops). USE WHEN: exploring driver architecture, finding all implementations of a callback interface, or checking which drivers implement a specific operation. Works with C designated initializers (.field = func patterns). Filter by structType and/or fieldName, or omit both to list all ops struct registrations in the codebase.

Discovers test files and functions that exercise specific code. USE WHEN: modifying code to know which tests to run/update, debugging to find test cases, or assessing test coverage. Returns tests array (name, id, relationship) for the target symbol, plus total count. Finds tests by tracing Calls edges to functions with test-like names (test_, _test). Requires uri and line parameters.

Generate a structured ARCHITECTURE.md from the code graph. Produces a markdown document covering: project overview (file/function/language counts), module breakdown (per-directory summaries with key exports, dependencies, complexity hotspots), hot paths (most-called functions), and architectural concerns (circular deps). The output can be saved to a file and then indexed via codegraph_index_markdown for future verify_design checks. USE WHEN: onboarding to a new codebase, generating initial documentation, or refreshing stale docs.

Gathers comprehensive code context optimized for AI understanding. USE WHEN: explaining code, planning modifications, debugging issues, or writing tests. THIS IS YOUR PRIMARY TOOL for understanding unfamiliar code. Returns: primaryContext (full source code), relatedSymbols (full source or signature-only when budget is tight), imports (file-level module imports), siblingFunctions (other functions in same file with signatures), dependencies, architecture (module, layer, neighbors), and debugHints (complexity, branches, exception handlers, early returns — debug intent only). Intent controls prioritization: 'explain' = dependencies + callers + siblings, 'modify' = tests + callers, 'debug' = call chain + debug hints, 'test' = example tests + mockable dependencies. maxTokens controls budget — high-priority sections get full source, remaining budget fills with signature-only symbols for maximum coverage. Requires uri and line parameters.

Maps function call relationships showing callers and callees. USE WHEN: tracing execution flow, understanding function usage, finding dead code, or debugging. Returns nodes with name, type, file path, and line range for each caller/callee in the chain. Use depth to control how many levels to traverse. Requires uri and line parameters.

Finds all functions called by a target function (forward call graph). USE WHEN: understanding function dependencies, tracing execution flow, or analyzing what code a function touches. SIMPLER than traverse_graph for this common use case. Returns callees array with symbol name and node ID. Use depth>1 to trace the full callee chain (what those callees call). Identify target via uri+line or nodeId from symbol_search.

Finds all functions that call a target function (reverse call graph). USE WHEN: understanding function usage, finding all invocation sites, or assessing change impact. SIMPLER than traverse_graph for this common use case. Returns callers array with symbol name and node ID. Use depth>1 to trace the full caller chain (who calls the callers). Identify target via uri+line or nodeId from symbol_search.

Discovers and assembles context across the entire codebase for a natural language query. USE WHEN: you need to understand a concept, pattern, or subsystem that spans multiple files — e.g., 'how does authentication work?', 'what handles database connections?', 'error handling patterns'. Unlike codegraph_get_ai_context (single symbol) or codegraph_get_edit_context (single location), this searches the whole codebase and curates cross-cutting context. Pipeline: (1) searches for relevant symbols matching query, (2) resolves full source code for top matches, (3) walks dependency graph to find related modules, (4) fetches relevant memories, (5) curates everything within token budget prioritized by relevance. EXAMPLE: query='authentication middleware' returns the auth middleware function source, its callers (routes using it), its dependencies (token verification, user lookup), and any architectural decisions or debug notes about auth.

Analyzes file import/dependency relationships. USE WHEN: understanding module architecture, finding circular dependencies, planning refactoring, or tracing import chains. Returns a graph of files connected by import edges. direction='imports' shows what this file depends on, 'importedBy' shows what depends on this file, 'both' shows full picture. depth controls how many levels to traverse (1=direct only). Requires uri parameter (file URI).

Gets comprehensive symbol details including source code and relationships. USE WHEN: you need full context about a symbol — source code, callers, callees, complexity, and metadata together. MORE COMPLETE than get_symbol_info but heavier. Returns: symbol (name, kind, signature, visibility, uri, line_range, properties), source (full source code string), callers (array), callees (array). Toggle includeSource/includeCallers/includeCallees to control response size. Identify symbol via uri+line or nodeId.

Assembles everything needed to edit code at a specific location in a single call. USE WHEN: you are about to modify, refactor, or fix code and need full context before making changes. PREFER THIS over codegraph_get_ai_context when you are about to write or modify code — it includes callers (impact), tests (what to update), and git history (recent context) that get_ai_context does not. Use get_ai_context instead when you only need to understand or explain code. Returns 5 sections: (1) symbol — full source code of the function/method at the given line, (2) callers — functions that call this symbol (to assess impact of changes), (3) tests — related test functions (to know what to update/run), (4) memories — relevant debug notes, architectural decisions, and known issues, (5) recentChanges — recent git commits that touched this file. EXAMPLE: Before modifying a function's signature, call this to see all callers that would break, tests that need updating, and whether someone recently changed this code. Token budget controls total context size with priority: symbol > callers > tests > memories > git history. Requires uri and line parameters.

Get a high-level summary of a module or directory — file count, function count, language breakdown, top complex functions, and external dependencies. Great for understanding unfamiliar code areas.

Gets quick metadata about any symbol (function, class, variable, type). USE WHEN: you need to quickly understand what a symbol is, check its signature, or see usage count. FASTER than codegraph_get_ai_context when you only need basic info. Returns: name, kind, signature, visibility, file path, line range, and properties (is_async, is_static, etc.). Set includeReferences=true to also get all reference locations (slower). Requires uri and line parameters.

Add an entire directory to the code graph without clearing existing data. USE WHEN: you need to explore a new codebase (e.g., kernel headers, another driver's source) alongside already-indexed code. Recursively indexes all supported files, resolves cross-file imports, and rebuilds search indexes. Does NOT clear existing graph data — new files are added alongside. Set embed=true to also build embeddings for similarity tools. Requires path parameter (absolute directory path).

Add or update specific files in the code graph without full reindex. USE WHEN: new files were created, existing files were modified, or you need specific files re-indexed immediately. Removes old data for each file before re-parsing — safe to call on already-indexed files. Resolves cross-file imports and rebuilds search indexes. Much faster than full reindex. Requires paths parameter (array of absolute file paths).

Index a local markdown file (ARCHITECTURE.md, API_DESIGN.md, etc.) into the persistent docs store. Parses the heading hierarchy, embeds leaf sections, and stores them so codegraph_search_docs can retrieve relevant sections in future sessions without re-reading the file. Returns the list of indexed chunks with their heading paths. USE WHEN: you want the agent to have design context across sessions without burning tokens re-reading the doc every time.

List all markdown files that have been indexed into the docs store via codegraph_index_markdown. Returns source file paths. USE WHEN: checking what docs are already indexed before indexing or searching.

Finds memories relevant to current code location. USE WHEN: starting work on a file/function to see past context. THIS SHOULD BE YOUR FIRST CALL when starting work on unfamiliar code. Returns memories array (id, title, content, kind, score, tags) ranked by relevance to the file/line. Optionally filter by kinds. Provide line for function-level precision.

Retrieves full memory details by ID. USE WHEN: you have a memory ID from search results and need complete content.

Marks memory as outdated without deleting. USE WHEN: knowledge is superseded, bugs are fixed, decisions are reversed. Maintains history while preventing outdated info from surfacing.

Lists memories with filtering and pagination. USE WHEN: browsing available memories or auditing stored knowledge.

Searches memories with hybrid BM25 + semantic + graph proximity. USE WHEN: recalling past knowledge — previous debugging sessions, architectural decisions, known issues. ALWAYS SEARCH before starting complex tasks. Returns results array (id, title, content, kind, score, tags, created_at) sorted by relevance. Filter with kinds (debug_context, architectural_decision, known_issue, convention, project_context), tags, or codeContext (node IDs for proximity boosting). Set currentOnly=false to include invalidated memories.

Get statistics about stored memories - counts by kind, total storage, etc.

Persists knowledge for future sessions. USE WHEN: discovering important context worth remembering — debugging insights, architectural decisions, known issues, coding conventions, or project-specific knowledge. Returns the stored memory ID. Each kind has specific optional fields: debug_context uses problem+solution, architectural_decision uses decision+rationale, known_issue uses description+severity. Tags improve future retrieval.

Analyze the current branch's changes against the code graph. Runs git diff to find changed files, then for each changed function: who calls it (blast radius), what tests cover it, which modules are affected. Returns a combined PR review context in one call — replaces manually running analyze_impact + find_related_tests on each file. USE WHEN: reviewing a PR, preparing a commit message, or checking what a branch might break before merging.

Reindex the workspace to refresh the code graph. Default is INCREMENTAL — only re-parses files that changed since last index (much faster). Set force=true for full rebuild when parsers were updated or graph is corrupted.

Remove all indexed chunks from a specific source file. Use codegraph_list_doc_sources first to see available sources. USE WHEN: a doc is outdated and you want to clear it before re-indexing, or to clean up the docs store.

Find functions that throw, catch, or handle specific error types. USE WHEN: understanding error flow, finding where exceptions originate, or auditing error handling coverage. Scans function body_prefix and signature for language-specific error patterns (Rust: Err(/panic!/anyhow, Python: raise/except, JS/TS: throw/catch, Go: errors.New/if err != nil, Java/C#: throw/catch). Optionally filter by a specific error type string and by role (throws vs catches). Returns functions with matched error_patterns and error_role ("throws", "catches", or "both").

Search code using regex patterns across function bodies, signatures, names, and docstrings. USE WHEN: finding specific code patterns (e.g., 'unwrap\(\)' calls, SQL queries, error handling patterns). More precise than symbol_search when you know the exact pattern. Returns matches with node_id, name, kind, path, line range, matched_in (which scope matched), matched_text (snippet up to 200 chars), and signature.

Semantic search over project docs previously indexed via codegraph_index_markdown. Returns matching doc sections with heading-path breadcrumbs (e.g. "Authentication > JWT > Refresh Token Rotation"), relevance scores, and source file provenance. USE WHEN: you need design context, architecture decisions, or API specs that were captured in project markdown files. Complements codegraph_memory_search (which stores ad-hoc notes) — this searches structured project documentation.

Searches codebase for symbols by name or pattern. USE WHEN: finding function/class implementations, exploring unfamiliar code, or locating specific functionality. THIS IS YOUR STARTING POINT when you don't know where code is located. Supports both exact name matching and natural language queries (e.g., 'function that validates email addresses'). Returns array of matches, each with: name, kind (function/class/method/variable/interface/type/module), file path, line range, signature, and docstring. Use compact=true for minimal output (name, kind, location only). symbolType filters by kind — use 'any' to search all types.

Advanced graph traversal for complex code exploration. USE WHEN: specialized analysis requiring custom traversal (not covered by get_callers/get_callees/get_dependency_graph). PREFER simpler tools for common cases. Returns nodes and edges discovered during traversal. edgeTypes filters which relationships to follow (e.g., ['calls', 'imports']). nodeTypes filters which node kinds appear in results. Identify start node via uri+line or startNodeId from symbol_search.

Cross-reference an indexed design doc against the code graph. Extracts backtick-wrapped identifiers from the doc (e.g. `UserService`, `authenticate()`, `POST /payments`) and checks each against the code graph via symbol search. direction='forward' (default): doc claims → code existence. direction='reverse': public code symbols → doc mentions. direction='both': both directions in one call. Returns verified/unverified with heading-path context. USE WHEN: checking whether the codebase matches the design doc, or after a refactor to see if the doc is still accurate.