Grasp — Code Architecture & Dependency Analysis

Ask natural language questions about the codebase architecture using the Grasp brain. Examples: "what are the most complex files?", "show me security issues", "which files have the highest blast radius?", "show me files with grade F".

Analyze a repo or local path and persist the result into the Grasp brain database (~/.grasp/brain.db) for fast offline queries.

List all repos indexed in the Grasp brain database.

Ranks files by Brandes betweenness centrality on the file-level call graph. Bridge nodes sit on the critical path between many other files — chokepoints that propagate change broadly. For graphs > 500 nodes the algorithm samples 100 random sources and rescales (approximate).

Parse a webpack/rollup/esbuild stats.json and map bundle sizes onto the files in a Grasp session. Returns per-file bundle size sorted largest-first. Helps identify which files contribute most to final bundle weight.

Given a list of changed files (e.g. from a PR diff), returns a composite risk score 0–100 with per-component breakdown. Designed for agent decision-making: if risk > 70, require second reviewer. Formula: risk = blast_radius×0.35 + complexity×0.25 + churn_frequency×0.20 + layer_violations×0.20 Score ≤ 33 = low, 34–66 = medium, 67+ = high. Parameters: session_id: string — active analysis session changed_files: string[] — list of file paths that changed Returns: { score: number, level: "low"|"medium"|"high", components: {blastRadius, complexity, churnFrequency, layerViolations}, affected…

Returns the latest GitHub Actions workflow run status for a repo — whether CI is passing, failing, or in progress. Use to check build health alongside grasp_analyze or grasp_commits.

Returns commit counts for the last 7 days and 30 days for a GitHub repo, plus commits since a given timestamp (useful for tracking how many commits landed since your last Grasp analysis). Use alongside grasp_analyze to detect when a repo has changed.

Detect cohesive file communities (bounded contexts / microservice candidates) in the codebase using Louvain-style greedy modularity optimization. Returns: - communities: list of {id, label, files, internal_edges, external_edges, cohesion} - modularity_score: Q ∈ [-0.5, 1.0] — higher is more modular - merge_suggestions: small communities that likely belong together Use this to identify microservice split points, bounded contexts, or team ownership boundaries.

Compute confidence scores (0.0–1.0) for all cross-file connections in the session. - 1.0: explicit static import + direct call - 0.8: same folder / same module cluster - 0.6: cross-folder, inferred (call count ≥ 3) - 0.4: low-frequency or dynamic-style call Returns connections sorted by confidence descending with aggregate stats. Use min_confidence to filter low-signal edges from downstream tools.

Run grasp.yml architecture rules against a session — returns violations with severity and file

Get architectural context for a file from the Grasp brain: health grade, complexity, coupling, churn, dependents, dependencies, and security issues.

Analyse contracts between a provider repo and one or more consumer repos. The provider's exported functions define the contract. Each consumer session is checked to verify it only calls functions that exist in the provider's exports. Returns: - contracts: list of exported functions in the provider with usage counts across consumers - violations: consumer calls to functions NOT in the provider's exports (broken contracts) - coverage_pct: % of provider contract used by consumers - orphaned: exported provider functions used by nobody Requires two or more grasp_analyze sessions — one for the pr…

Show which team members own the most code, identify bus-factor files (single contributor), and reveal team silos. Uses git history from a local repo. Returns per-contributor stats and files with single-author risk.

Parse a coverage file (lcov.info or Istanbul/NYC coverage-final.json) and return per-file coverage percentages mapped against files in a Grasp session. Use after grasp_analyze to get a combined "coverage + hotspot" view. Files with high churn AND low coverage are your riskiest files.

Identifies functions with no test coverage using COVERS graph edges. Returns uncovered functions sorted by call frequency (most-called untested first), risky uncovered functions in high-churn files, per-directory coverage percentages, and an overall coverage estimate. Requires grasp_analyze to have been run first.

Compares two analyzed sessions to find shared patterns, naming clashes, duplicated logic, and suggests shared library extractions. Also reports workspace sub-packages for monorepos.

Find all circular dependency chains in the codebase. Circular deps cause tight coupling, make testing difficult, and can cause runtime errors. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - limit (number, optional): Max cycles to return (default: 20) Returns: { "total": number, "cycles": [ { "length": number, // Number of files in the cycle "files": string[], // Files in the cycle (A → B → C → A) "display": string // Human-readable: "a.py → b.py → c.py → a.py" } ] …

Scans source files for ORM model definitions (SQLAlchemy, TypeORM, Sequelize, Prisma, Drizzle, Mongoose) and raw SQL/query patterns to produce a file-to-table coupling report. Identifies god tables (touched by many files), high-coupling files (touch many tables), and shared-table clusters that indicate tight coupling. Use after grasp_analyze.

Returns packages found in package.json dependencies/devDependencies that are not imported by any code file. Useful for pruning bloat from node_modules. Use after grasp_analyze on a Node.js project.

Find all files that import a given npm/pip/go package and show the blast radius of upgrading or removing it. Scans file content for import/require/from statements matching the package name. Returns affected files sorted by churn (riskiest changes first), plus the transitive blast radius.

Get all files that depend on a specific file (incoming dependencies — what calls into it). Useful for blast radius analysis: "what breaks if I change this file?" Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - file_path (string): Relative path to the file Returns: { "file": string, "depended_on_by": [ // Files that call into this file { "file": string, "functions_used": string[], "call_count": number } ], "blast_radius": number, // Count of dependent files "total": numbe…

Query deps.dev for how many public packages in the ecosystem depend on this repo/package. Shows dependent count across npm/PyPI/Go/Maven.

Maps git diff output to affected symbols and execution processes. Given a local repo path and scope, runs git diff, extracts changed line ranges, and cross-references them with the indexed function table in the Grasp brain store. scope options: - unstaged: git diff (working tree vs index) - staged: git diff --cached (index vs HEAD) - all: git diff HEAD (all uncommitted changes) - compare: git diff {base_ref}...HEAD (branch comparison) Returns: changed files, affected symbols (with file+line), affected processes (BFS-traced from entry points), and a risk level (LOW/MEDIUM/HIGH/CRITICAL).

Generates architecture diagrams from analysis data. Output pastes directly into GitHub wikis, Notion, Confluence. Formats: mermaid (default) | c4-context | c4-container | c4-component Parameters: session_id: string format: "mermaid"|"c4-context"|"c4-container"|"c4-component" (default "mermaid") layer: string (only for c4-component) max_nodes: number (default 50) Returns: { diagram: string, format: string, nodeCount: number, tip: string }

Compare two analysis sessions to see what changed between them — files added/removed, health score delta, new/resolved issues, dependency count change, and new circular dependencies. Parameters: session_id_a — the baseline session (older snapshot) session_id_b — the comparison session (newer snapshot) Returns a structured diff report.

Compares two architecture snapshots saved via grasp_snapshot and reports drift. Returns health score delta, new circular dependencies, files with significantly increased coupling, and a drift_level of STABLE | DEGRADED | CRITICAL. Use in CI to gate merges on architectural quality.

Parse a unified git diff and map changed line ranges to function/class definitions in the analysed codebase. Returns: - changed_symbols: list of functions/classes touched by the diff, with file, line, and caller count - blast_radius_total: sum of unique files that depend on any changed symbol - diff_files: list of source files mentioned in the diff Pipe `git diff HEAD~1` (or any unified diff) into the `diff` parameter.

Estimate DORA metrics (Deployment Frequency, Lead Time, Change Failure Rate, MTTR) from GitHub API data

Scans the codebase for separation-of-duties violations — cases where the same file or module both initiates a transaction/action AND approves/validates it. Critical for SOX, FDA 21 CFR Part 11, and security-sensitive systems. Args: - session_id: analysis session - initiation_patterns: regex patterns identifying "initiate" code (optional, defaults to common financial/command patterns) - approval_patterns: regex patterns identifying "approve/validate" code (optional, defaults to common approval patterns)

Check ESA software engineering standard ECSS-E-ST-40C compliance. Verifiable rules: DI-01 (unique IDs in file headers), DI-04 (documented interfaces), DI-07 (test coverage), DI-10 (no circular deps), DI-15 (no dead code).

Generates iframe embed code, a README badge, and a direct shareable link for any public GitHub repository so it can be visualized via Grasp without installation.

Scans all files for environment variable reads. Cross-references with .env.example to find undocumented vars. Tags each var with which architectural layer reads it and whether it appears only in test files. Parameters: session_id: string — active analysis session Returns: { vars: [{name, files, layers, inEnvExample, testOnly}], undocumented: string[], testOnly: string[] }

Trace which codebase files are reached by eval/test scripts and identify safety-critical files with no eval coverage

Maps event emitters and subscribers across the codebase. Builds a pub/sub dependency graph that import analysis cannot see. Detects orphaned events (emitted, never subscribed) and ghost subscribers (subscribed, never emitted). Patterns detected: Node.js EventEmitter, browser addEventListener/dispatchEvent, Redux dispatch, pub/sub libraries. Parameters: session_id: string — active analysis session Returns: { events: [{name, emitters, subscribers, orphaned, ghost}], orphanedCount, ghostCount }

Trace execution flow from a named entry-point function through the call graph using BFS, labelling each hop as a STEP_IN_PROCESS edge. Returns: - steps: ordered list of {step, function, file, called_by} — the execution chain - mermaid: a Mermaid flowchart LR diagram of the traced path - edge_count: total STEP_IN_PROCESS edges found Use this to understand what a function triggers end-to-end, ideal for onboarding and PR review.

Generate a plain-English structural explanation for a file or function in the analysed codebase. Describes the file's role, layer, dependencies, complexity, and top functions, or explains a specific function's purpose based on its name and call graph.

Exports the analysis as three CSVs: files (path/layer/language/lines/complexity/churn/fan_in/fan_out/has_security_issue), connections (source/target/count), and issues (type/severity/file/description). The `format` parameter controls which sheet is returned. Default `bundle` returns all three concatenated with `--- <name>.csv ---` separators.

Exports the analysis graph as Neo4j CREATE statements: (:File) and (:Function) nodes, (:File)-[:DEFINES]->(:Function) and (:File)-[:IMPORTS]->(:File) relationships. Paste into Neo4j Browser or pipe to cypher-shell.

Exports the dependency graph as a Terrastruct D2 diagram with `direction: right`, layer containers, and import edges. Render with the `d2` CLI to SVG / PNG / PDF.

Exports the dependency graph as a Visual Studio Directed Graph (DGML) XML document. Opens natively in the Visual Studio Architecture window and is consumable by other Microsoft architecture tools.

Exports the dependency graph as a Graphviz `digraph` (DOT). Files are clustered into `subgraph cluster_<layer>` blocks, layer-coloured nodes carry path + LOC labels, and edges are labelled with import counts when > 1. Render with `dot -Tsvg` / `dot -Tpng` or paste directly into GitHub which renders DOT inline.

Exports the dependency graph as a draw.io (`.drawio`) XML document with a simple grid layout (one column per layer). Open and edit in https://app.diagrams.net or the VS Code draw.io extension.

Exports the dependency graph as a GEXF 1.3 document — Gephi's native format. Carries node attributes (layer, lines, complexity, churn) and weighted edges. Richer than GraphML for Gephi-based analysis.

Exports the analysis graph as a GraphML XML document compatible with yEd, Gephi, Cytoscape and similar tools. Nodes carry label/layer/language/lines attributes; edges carry edgeType="imports".

Exports the dependency graph as a Mermaid `graph LR` document with one subgraph per layer. Renders inline on GitHub, GitLab, Notion, Obsidian, and most modern markdown viewers.

Exports the analysis graph as an Obsidian .canvas JSON document. Files are grouped by layer into vertical columns; layer-coloured nodes are connected by import edges. Save the output as <name>.canvas inside an Obsidian vault to open it.

Exports the dependency graph as a PlantUML class diagram (`@startuml ... @enduml`) with one `package` per layer and `-->` edges for imports. Compatible with Confluence, Jira, IntelliJ, and the PlantUML server.

Finds all feature flag reads in the codebase. Supports LaunchDarkly, GrowthBook, OpenFeature, env-var flags (FEATURE_X, FF_X, ENABLE_X), and custom patterns (flags.get, features.enabled, isFeatureEnabled). Parameters: session_id: string — active analysis session Returns: { flags: [{name, source, files}], totalFlags: number }

Get all files that a specific file depends on (outgoing dependencies — what it calls into). Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - file_path (string): Relative path to the file (e.g. "src/auth.py", "lib/utils.ts") Returns: { "file": string, "depends_on": [ // Files this file calls into { "file": string, "functions_called": string[], "call_count": number } ], "total": number }

Find the shortest dependency path between two files. Useful for understanding how file A connects to file B through the call graph. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - from (string): Source file path - to (string): Target file path Returns: { "from": string, "to": string, "path": string[], // Files in the dependency chain "length": number, // Hops in the chain "found": boolean }

Compare a fork session against its upstream session. Shows diverged files, identical files, fork-only files, and the blast radius of merging upstream back.

Generate an AGENTS.md file for the repo with architecture context: health grade, critical issues, functional areas, and grasp usage instructions. Write to the repo root or a custom output_path. Returns the path written.

Generate per-functional-area skill files under .claude/skills/generated/ in the repo root. Each file documents the files, exported API, and dependencies of one functional area (top-level folder). Returns list of files written. These skill files can be used by Claude Code (via the Skill tool) to give focused context when navigating each module.

Identify ideal first-contribution targets: isolated files (fan-in ≤ 2), low complexity (< 10 functions), no test counterpart, stable (not in active churn). Returns ranked suggestions with GitHub issue draft text.

Returns the Kuzu graph schema for the indexed repo: all node table names, edge table names, their fields, and row counts. Use to understand what Cypher queries are possible via grasp_graph_query.

Add a repository to a named group for multi-repo fan-out queries. Groups are stored in ~/.grasp/groups.json. Once added, use @groupName as the source in grasp_search, grasp_ask, grasp_context, and grasp_route_map to query all repos in the group at once. Args: - group: group name (e.g. "backend-services", "platform") - source: repo source string (must already be brain-indexed)

List all named repo groups and their members. Groups are stored in ~/.grasp/groups.json and created via grasp_group_add.

Overlay heritage manifest (which files came from prior missions/versions) on the codebase. Returns heritage coverage %, delta complexity, and files with zero delta (reuse candidates for certification shortcut).

Generate ready-to-use AI tool configuration files from the analysed codebase. Outputs: - claude_settings_json: .claude/settings.json with a PostToolUse hook that warns when edits touch critical files - cursor_mdc: .cursor/rules/grasp.mdc with layer constraints and critical file annotations - claudemd_snippet: paste into CLAUDE.md to inject architecture context into every session The hook warns the AI when it edits a high-fan-in file, prompting it to check downstream callers.

Get the most problematic files ranked by a combination of coupling, complexity, and size. These are the highest-risk files to change and best candidates for refactoring. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - limit (number, optional): Number of files to return (default: 15) - sort_by ("coupling" | "complexity" | "size" | "combined"): Ranking strategy (default: "combined") Returns: { "hotspots": [ { "path": string, "name": string, "layer": string, "fan_in": number, // Files that depen…

Ranks files by total connectivity (fan-in + fan-out). Top hubs are the most coupled files in the codebase — likely god-objects or core abstractions.

Match ICD (Interface Control Document) entries to code functions. Flags unimplemented interfaces (ICD entry with no matching function) and undocumented interfaces (function with no ICD entry).

Ingest any artifact — a file, a directory, or a URL — into Grasp's semantic knowledge graph. Handles code, Markdown/text, PDF, Word (.docx), Excel (.xlsx), HTML, images (OCR), audio/video (local Whisper transcription), and YouTube links. Entities and relationships are extracted (tagged EXTRACTED vs INFERRED) and stored for querying with grasp_ask. Uses a configured LLM when available, otherwise a deterministic local extractor. Optional parsers (pdf-parse, mammoth, xlsx, tesseract.js) install on demand.

Detect interrupt handler patterns and trace their call chains. Flags: dynamic allocation (malloc/new) in IRQ chain, sleeping calls in IRQ chain, excessive call depth from interrupt context.

Fetch open GitHub Issues for a repo and map them to files in a Grasp session. Files mentioned most in issues are your "business pain hotspots". Requires a GitHub token for private repos or to avoid rate limits.

Map Jira issues to source files — finds which files are referenced in issue titles and descriptions

Parse Kconfig files and #ifdef CONFIG_* patterns in C files. Maps config options to conditionally compiled files. Detects high-risk toggles (affecting >50 files) and dead code under specific configs.

Ask a natural-language question answered from the ingested knowledge graph, grounded with citations. Uses hybrid lexical+vector retrieval plus graph facts; synthesizes prose with a configured LLM, or returns a sourced digest when none is set.

Explain a concept/entity from the knowledge graph: its type, its graph neighbourhood (relationships, tagged EXTRACTED/INFERRED), and the sources where it appears.

Export the semantic knowledge graph to a portable format: cypher (Neo4j/FalkorDB), graphml (Gephi/yEd), json, or mermaid (diagram). Optionally write to a file path.

Summarise the knowledge graph: document/chunk/entity/relationship counts, EXTRACTED vs INFERRED split, and the most-connected entities ("god nodes").

Trace the shortest relationship path between two concepts/entities in the knowledge graph.

Surfaces three classes of risk: (1) isolated code files (no callers + no callees, likely dead), (2) untested hotspots (high fan-in but no matching test file), (3) weak communities (layers with < 3 files but > 5 outgoing edges).

Detects code patterns that introduce latency risk in high-frequency trading or latency-sensitive financial systems — synchronous blocking calls in hot paths, GC-inducing allocations in loops, unnecessary serialization, lock contention patterns. Args: - session_id: analysis session - language: language to scan for (default 'auto' — detected from file extensions) - severity_threshold: filter results by minimum severity: 'all', 'high', 'critical' (default 'all')

Scans node_modules/ for all dependency licenses. Categorizes as permissive (MIT, Apache-2.0, BSD, ISC), copyleft (GPL, AGPL, LGPL), or unknown. Returns violations and summary counts. Parameters: session_id: string — active analysis session flag_copyleft: boolean (default true) allowed_licenses: string[] (optional) — SPDX list of allowed licenses Returns: { dependencies: [{name, version, license, licenseCategory}], summary: {total, permissive, copyleft, unknown}, violations: [{name, license}] }

List which LLM backends are currently usable (based on environment keys and a local Ollama probe). Diagnostics for the semantic tools.

Get per-file metrics: lines, functions, cyclomatic complexity, fan-in, fan-out, and churn. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - file_path (string, optional): Get metrics for a specific file. If omitted, returns all files sorted by complexity. - limit (number, optional): Max files to return when listing all (default: 30) Returns for specific file: { "path", "lines", "functions", "complexity", "nesting_depth", "fan_in", "fan_out", "churn", "layer" } Returns for all files: { "files": [...], "total": number }

Analyzes import usage across source files and produces a phased, topologically-ordered migration plan for replacing one package or module with another (or removing it). Returns per-file effort estimates and action items. Use after grasp_analyze.

Returns a very compact (~100 token) summary of the repo: name, file count, health grade/score, top languages, top hubs, layers, and circular-dep flag. Designed as the LLM's first call to orient itself before deeper queries.

Audits quantitative financial code for model risk — validates that pricing models, risk calculations, and valuation functions follow best practices: test coverage, parameter validation, numerical stability checks, documentation, and version control patterns. Args: - session_id: analysis session - model_paths: optional list of path prefixes to restrict audit (e.g. ["src/pricing/", "models/"])

Compute Method Resolution Order (MRO) for class hierarchies in Python, Ruby, and Java/Kotlin. - Python: C3 linearization (same algorithm as CPython) - Java/Kotlin/Scala: linearization following single-inheritance chain + interfaces - Ruby: include/prepend order Returns per-class MRO chains and flags methods overridden at multiple levels. Useful for understanding polymorphism, debugging unexpected method dispatch, and refactoring class trees.

Detect cross-language call boundaries: Ada pragma Import/Export to C, Python ctypes/cffi calling C, JavaScript calling Rust/WASM. Renders cross-language edges and flags safety gaps where rules may not be caught across the boundary.

Produces an ordered reading path for a new engineer entering a specific area of the codebase. Given a topic/area query, returns 5–15 files sorted by "must understand first" order (low architectural layer + high fan-in = read first). Parameters: session_id: string — active analysis session query: string — area to explore (e.g. "auth", "payments", "src/services/user.ts") limit: number (default 12) — max files to return Returns: { path: [{file, layer, fanIn, whyFirst, connectsTo}], topic: string, totalMatched: number }

Merge multiple analysis sessions into a single org-level graph. One node per repo, edges = inter-repo package dependencies detected by matching package.json names across sessions. Use after running grasp_analyze on 2+ repos. Args: - session_ids: array of 2+ session IDs to merge - include_shared_libs: include shared library nodes used by 3+ repos (default true)

Analyzes all public repositories in a GitHub org and returns a rolled-up health dashboard. Fetches up to max_repos repos (sorted by stars), analyzes each in parallel, and aggregates health grades, security counts, language distribution, and top churn files.

Detects ORM query patterns (Prisma, TypeORM, Sequelize, SQLAlchemy) across the codebase and returns all database operations grouped by model. Shows which functions query which models, operation types, and call frequencies. Use to understand data access patterns, audit database usage, find N+1 risks, or plan schema migrations.

Given an ordered list of commit SHAs, rank patches by blast radius and subsystem crossings. Helps kernel/OS reviewers prioritize which patches in a series need most attention.

Get design patterns detected in the codebase: Singleton, Factory, Observer, hooks, decorators, middleware, and anti-patterns like God Objects. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - include_anti_patterns (boolean, optional): Include anti-patterns like God Object and Long File (default: true) Returns: { "total": number, "patterns": [ { "name": string, "desc": string, "severity": string, "is_anti_pattern": boolean, "file_count": number, "files": [{"name": string, "path": st…

Static analysis for common performance anti-patterns: N+1 ORM queries in loops, synchronous I/O on the event loop, JSON serialization inside loops. Each finding includes file, line, severity, and a fix suggestion. Parameters: session_id: string — active analysis session Returns: { findings: [{file, line, pattern, severity, message, suggestion}], criticalCount, warningCount }

Trace all code paths that touch user-marked PII entry points (personally identifiable information, financial data). BFS through dependents, flags risky patterns: logging, unencrypted storage writes, URL parameters, external API calls. Args: - session_id: analysis session - pii_sources: file paths marked as PII entry points

Detect plugin extension points (registerPlugin, use(), extend(), addHook() patterns) and map which files expose them vs which files implement plugins. Flags tightly-coupled extension points (fan-in > 10).

Generates a formatted GitHub PR comment with health score, grade, key metrics, and changed-file impact. Optionally accepts a list of changed files to show blast radius. Use after grasp_analyze.

Posts inline code review comments on a GitHub Pull Request at exact lines with high-severity findings. Posts per-line annotations visible in the PR diff view — like Reviewdog. Only posts for: complexity > min_complexity, circular dependency participant, or security issue. Parameters: session_id: string repo: string — "owner/repo" pr_number: number token: string — GitHub PAT with repo write access min_complexity: number (default 15) dry_run: boolean (default false) — returns comments without posting Returns: { posted: number, skipped: number, comments: [{path, line, body}], dryRu…

Analyzes a file or function within a session and produces a prioritized, step-by-step refactor plan. Considers complexity, fan-in/out, duplicates, layer violations, and circular deps. Use after grasp_analyze.

Given a regulatory document section (GDPR article, HIPAA rule, SOX control, PCI-DSS requirement) and keywords describing what that regulation requires in code, finds all files that implement or touch that regulatory area and estimates the blast radius of a compliance change. Args: - session_id: analysis session - regulation: human-readable regulation label, e.g. "GDPR Article 17 - Right to Erasure" - keywords: code-level keywords to search for, e.g. ["delete", "erasure", "forget", "remove", "purge", "user_data"] - scope_paths: optional list of path prefixes to restrict the search, e.g…

List all repositories indexed in the local Grasp Brain (~/.grasp/brain.db). Returns each repo with: source, health grade, file/function counts, last indexed timestamp, and active session IDs. Use this to get an overview of everything indexed, or to find the session_id for a previously analysed repo without re-running grasp_analyze.

Return the overall health of the Grasp registry: how many repos are indexed, how many have active sessions, total analysis coverage.

Rename a symbol (function, class, variable) across all files in a brain-indexed repo. Uses the brain store edges to locate every file that references the symbol, then produces a whole-word regex rename. By default returns a dry-run diff. Set apply=true to write changes to disk (local repos only). Args: - source: repo source — must be brain-indexed and local path for apply=true - old_name: exact symbol name to rename - new_name: replacement name - apply: false (default) = dry-run diff only; true = write changes to disk

Map requirements to source code — shows coverage, uncovered requirements, and unspecified code for DO-178C / ECSS compliance

Resolve the concrete class for every class method in the codebase — determining what type `self` (Python) or `this` (JS/Java/Ruby) refers to. Returns: - resolutions: list of {method, class, file, line, language, callers} — the resolved receiver chain - ambiguous: methods defined on multiple classes (diamond inheritance / duck typing) - unresolved: methods that could not be mapped to a class Useful for understanding polymorphism, tracing method dispatch, and refactoring class trees.

Assess whether a candidate module can be safely reused in a target project — produces Red/Amber/Green compatibility matrix across interface, dependencies, security, and architecture

Scan a repo for HTTP route definitions and map each route to its handler function. Supports: Express/Fastify/Hono (JS/TS), FastAPI/Flask (Python), Gin (Go). Returns a table of: METHOD, PATH, handler function name, file, line number. Requires a local-path source or an active session_id.

Evaluate a set of FORBIDDEN dependency rules against a prior analysis session. Reads rules from a .grasprules file in the repo root (if path provided) or accepts inline rules. Returns violations grouped by rule — pipe into CI to enforce architecture boundaries. Rule format: { "from": "utils", "to": "services", "type": "FORBIDDEN", "reason": "..." }

Diff two training run configs (YAML or JSON) and identify which code files are affected by each changed hyperparameter or data pipeline key

Reads a .grasp-trace.json file produced by the GraspTracer and overlays actual runtime call frequencies and durations onto the static analysis. Returns hot files, hot paths, and a merged edge list. Use after instrumenting your app with the GraspTracer from grasp-mcp-server/runtime-tracer.

Identify ungated output paths — paths from entry points to output files that do not pass through any designated safety gate file

Serializes a Grasp analysis session to SARIF 2.1.0 JSON format suitable for upload to GitHub Code Scanning via the upload-sarif action. Returns the full SARIF document as a string. Use after grasp_analyze.

Generate a Software Bill of Materials (CycloneDX or SPDX) from dependency files detected in the analysed repo

Hybrid search over a brain-indexed repo: BM25 full-text + vector semantic search merged with Reciprocal Rank Fusion (k=60). Results include process membership — which execution flows (entry-point → call chain) each function participates in. First call may trigger a one-time model download (~23 MB to ~/.grasp/models/). Subsequent calls are instant. Falls back to BM25-only if model unavailable. Args: - source: repo source string (must be indexed via grasp_brain_index first) - query: natural language or keyword query, e.g. "authentication token validation" - limit: max results to return …

Get security issues found in the codebase: hardcoded secrets, SQL injection risks, insecure patterns, etc. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - severity (string, optional): Filter by severity ("critical", "high", "medium", "low") - limit (number, optional): Max issues to return (default: 30) Returns: { "total": number, "issues": [ { "type": string, "severity": string, "file": string, "desc": string } ] }

Embeds every function signature in the session and returns the top-k matches by cosine similarity to the query. Falls back to substring keyword search on function names if embeddings are unavailable.

Compare two sessions and determine if the version bump in package.json is semantically correct. Breaking changes (removed exports) require at least a minor bump. New exports require at least a minor bump. Fixes only = patch is correct. Verdict: 'ok' | 'underbump' | 'breach' Note: AnalysisResult does not carry a packageVersion field. Versions must be supplied via the session source string or are reported as 'unknown'.

Build a service-level dependency graph from OTEL or custom trace JSON — maps inter-service call volumes

List all persisted analysis sessions. Sessions survive server restarts and expire after 7 days (configurable via GRASP_SESSION_TTL env var). Returns: { "sessions": [{ "session_id", "source", "analyzed_at", "last_accessed", "size_kb", "health_grade", "file_count" }], "storage": "~/.grasp/sessions/" }

For a given function name, trace how it is called across all files and flag argument count mismatches. Uses the brain store to find the function definition (parameter count) and all call sites. Flags callers that pass a different number of arguments than the definition expects. Requires the repo to be indexed via grasp_brain_index.

Deep duplicate and code-clone analysis for a session. Returns duplicate function clusters, most-duplicated files, and refactoring recommendations ranked by impact. Use after grasp_analyze.

Auto-generate a SKILL.md (or CLAUDE.md snippet) from the analysed codebase. The document covers: - Architecture overview (layers, top folders) - Critical files (highest fan-in) - Exported API surface (top exported functions sorted by caller count) - Detected patterns and anti-patterns - Open issues (critical + warnings) Paste the output directly into SKILL.md, CLAUDE.md, or a system prompt.

Saves the current graph state as a named snapshot for later drift comparison via grasp_diff_snapshots. Captures health score, coupling metrics, circular dep count, and per-file coupling. Use before/after significant changes, or in CI to track architectural health over releases.

Finds files that are active (imported by others) but potentially abandoned — low churn, high fan-in, no test counterpart. These are the "this probably still works but nobody knows why" files. Staleness score = (low_churn × 0.4) + (high_fanIn × 0.35) + (no_test × 0.25), normalized 0–100. Parameters: session_id: string — active analysis session min_fan_in: number (default 2) — minimum fan-in to consider limit: number (default 20) — max results Returns: { files: [{path, layer, fanIn, churn, hasTest, stalenessScore}] }

Detect directory-level subsystem groupings in C/C++ repos (networking, fs, mm, drivers, arch, crypto, etc.) and flag cross-subsystem dependencies. Also supports user-defined subsystems via custom boundaries.

Generate prioritised refactoring suggestions based on hotspot data, metrics, circular dependencies, and issues from a prior analysis session. Parameter: session_id — from grasp_analyze Returns a ranked list of actionable suggestions with rationale and estimated impact.

Auto-generates 5–10 thoughtful questions a code reviewer should ask, derived from the session's hubs, bridges, layer crossings, knowledge gaps, circular deps, and duplicates. Use as the opening agenda for an architecture review.

Finds dependencies that cross between architectural layers in unusual combinations. Sorts by rarity (1 - count(layer-pair) / total cross-layer edges). High-rarity edges are the most likely architecture violations.

Returns the last N git commits for a local path, with per-commit changed files. Use this to understand how the codebase evolved, spot high-churn periods, and identify which files change together.

Scan a repo for MCP tool registrations, gRPC service definitions, and RPC handlers. Returns a structured map of: tool/method name, type (mcp|grpc|rpc), file, line number. Useful for understanding what capabilities a service exposes, and for generating documentation. Requires a session_id or local source path.

Walks the file/function call graph from a start node, BFS by edges. Stops when accumulated token estimate >= max_tokens or depth >= max_depth. Direction = callers (fan-in), callees (fan-out), imports, or both.

Runs topological cross-file type inference on the session. Processes files in import-dependency order (Kahn's algorithm) and propagates known return types across call boundaries. Returns inferred types with confidence scores. Use to understand what types flow across module boundaries — helpful for refactoring return types or understanding data shapes without running the code.

Reports type annotation coverage per file — percentage of functions with type annotations. For TypeScript/TSX files: checks for type annotations in function signatures. Prioritizes high fan-in files (annotating them has the most downstream impact). Parameters: session_id: string — active analysis session min_fan_in: number (default 1) limit: number (default 20) — max files (sorted by lowest coverage first) Returns: { files: [{path, layer, fanIn, typedFunctions, totalFunctions, coveragePct}], averageCoverage: number }

Get functions that appear to be dead code — exported or defined but never called from other files. Requires a session_id from grasp_analyze. Args: - session_id (string): From grasp_analyze - file (string, optional): Filter to functions in a specific file path - limit (number, optional): Max results to return (default: 50) Returns: { "total": number, "dead_code_pct": number, "functions": [ { "name": string, "file": string, "line": number | null } ] }

Start/stop/status scheduled vulnerability re-scans. Persists scan history in brain.db and surfaces new CVEs since last scan. Actions: start (begin periodic scanning), stop (cancel watch), status (list active watches), history (past scan results for a repo).

Full security scan: (1) declared dependencies vs OSV.dev CVEs, (2) container/runtime images vs NIST NVD, (3) supply-chain integrity checks (lockfile hashes), (4) Socket.dev behavioral analysis for npm. Returns severity-classified findings with fix guidance.

Analyse a local directory and return a diff summary compared to the last time it was analysed. Call repeatedly to detect changes: new files, removed files, health score drift, new issues. Uses session IDs to compare across calls. First call returns baseline; subsequent calls return the diff.

Generate a complete markdown wiki for the repository from the analysis session. Produces: - index.md: overview, health grade, layers, critical files, top exported API - One page per top-level folder: files, key functions, fan-in - api.md: all exported functions sorted by caller count Paste into GitHub Wiki, Notion, Confluence, or .github/wiki/.

Trace where a return type flows through the codebase. Finds producer functions (those that return the type) and peer functions (those sharing the same return type) within N hops. Requires grasp_brain_index to have been run first. Example: type_propagation with typeName="Promise<User>" finds all functions returning Promise<User> and their call neighbors.