{
  "markdown": "<div align=\"center\">\n\n<img src=\"grasp-social-v2.png\" alt=\"Grasp — Code Architecture Suite\" width=\"100%\"/>\n\n> [English](README.md) · [हिन्दी](README.hi.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [简体中文](README.zh.md)\n\n<br/>\n<br/>\n\n<a href=\"https://github.com/ashfordeOU/grasp/actions/workflows/ci.yml\" target=\"_blank\"><img src=\"https://github.com/ashfordeOU/grasp/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"/></a>\n<a href=\"https://www.npmjs.com/package/grasp-mcp-server\" target=\"_blank\"><img src=\"https://img.shields.io/npm/v/grasp-mcp-server?label=MCP%20Server&color=00d4aa&style=flat-square&logo=npm\" alt=\"npm\"/></a>\n<a href=\"LICENSE\" target=\"_blank\"><img src=\"https://img.shields.io/badge/license-ELv2-4d9fff?style=flat-square\" alt=\"License\"/></a>\n<a href=\"https://ashfordeou.github.io/grasp\" target=\"_blank\"><img src=\"https://img.shields.io/badge/browser%20app-live-00d4aa?style=flat-square&logo=github\" alt=\"GitHub Pages\"/></a>\n\n<br/>\n\n**150 MCP tools + 8 Resources + 2 Prompts · 35 languages · 11 AI providers + 200+ models via OpenRouter · 10 graph views · multimodal knowledge graph · zero data collection**\n\n<br/>\n\n<a href=\"https://ashfordeou.github.io/grasp\" target=\"_blank\"><img src=\"https://img.shields.io/badge/▶%20Browser%20App-ashfordeou.github.io%2Fgrasp-0f2a2a?style=for-the-badge&color=0f2a2a&logoColor=00d4aa\" alt=\"Browser App\"/></a>\n&nbsp;\n<a href=\"https://github.com/ashfordeOU/grasp/releases/latest\" target=\"_blank\"><img src=\"https://img.shields.io/badge/VS%20Code-Install%20(.vsix)-007ACC?style=for-the-badge&logo=visual-studio-code\" alt=\"VS Code\"/></a>\n&nbsp;\n<a href=\"https://www.npmjs.com/package/grasp-mcp-server\" target=\"_blank\"><img src=\"https://img.shields.io/badge/MCP%20Server-npm-CB3837?style=for-the-badge&logo=npm\" alt=\"MCP Server\"/></a>\n&nbsp;\n<a href=\"https://plugins.jetbrains.com/plugin/31362-grasp--code-architecture-visualizer\" target=\"_blank\"><img src=\"https://img.shields.io/badge/JetBrains-Marketplace-000000?style=for-the-badge&logo=jetbrains\" alt=\"JetBrains\"/></a>\n&nbsp;\n<a href=\"https://addons.mozilla.org/firefox/addon/grasp-code-architecture\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Firefox-Add--ons-FF7139?style=for-the-badge&logo=firefox-browser&logoColor=white\" alt=\"Firefox Add-ons\"/></a>\n&nbsp;\n<a href=\"https://chromewebstore.google.com/detail/grasp-%E2%80%94-code-architecture/pipmlammandfhfbodllcjolgeolkhapj\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Chrome-Web%20Store-4285F4?style=for-the-badge&logo=google-chrome&logoColor=white\" alt=\"Chrome Web Store\"/></a>\n&nbsp;\n<a href=\"https://github.com/ashfordeOU/grasp/releases\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Safari-Sideload%20(macOS%2013%2B)-0D96F6?style=for-the-badge&logo=safari&logoColor=white\" alt=\"Safari sideload\"/></a>\n&nbsp;\n<a href=\"https://www.raycast.com/ashfordeOU/grasp\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Raycast-Store-FF6363?style=for-the-badge&logo=raycast&logoColor=white\" alt=\"Raycast Store\"/></a>\n&nbsp;\n<a href=\"https://zed.dev/extensions?query=grasp\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Zed-Extension-084CCF?style=for-the-badge&logoColor=white\" alt=\"Zed Extension\"/></a>\n\n<br/>\n\n<a href=\"https://ashfordeou.github.io/grasp\" target=\"_blank\">🌐 Browser App</a> &nbsp;·&nbsp;\n<a href=\"https://www.npmjs.com/package/grasp-mcp-server\" target=\"_blank\">📦 MCP Server</a> &nbsp;·&nbsp;\n<a href=\"https://github.com/ashfordeOU/grasp/issues\" target=\"_blank\">🐛 Report Bug</a> &nbsp;·&nbsp;\n<a href=\"https://github.com/ashfordeOU/grasp/issues\" target=\"_blank\">✨ Request Feature</a> &nbsp;·&nbsp;\n<a href=\"https://ashfordeou.github.io/grasp/docs/privacy.html\" target=\"_blank\">🔒 Privacy</a>\n\n</div>\n\n---\n\n## What's New in v3.21.0\n\n**New — Multimodal Knowledge Graph (MCP server).** Seven new MCP tools ingest your documents — PDF, DOCX, XLSX, HTML, images (OCR), audio/video (local Whisper via `@xenova/transformers` + ffmpeg), YouTube, and URLs — alongside your code into a queryable knowledge graph, then answer natural-language questions with citations: `grasp_ingest`, `grasp_kg_ask`, `grasp_kg_trace`, `grasp_kg_explain`, `grasp_kg_stats`, `grasp_kg_export`, `grasp_llm_status`. A **local-first** multi-LLM layer auto-detects Ollama before any cloud key and falls back to a zero-credential deterministic engine. Server-side only (Node MCP server, not the browser app) — see **Multimodal Knowledge Graph** under [Code Intelligence](#code-intelligence).\n\n**+3 native AST languages** — Bash, Elixir, and Julia take tree-sitter-backed function extraction, call counting, and complexity scoring to **19 languages**.\n\n**Optional MCP-over-HTTP bridge** — set `GRASP_HTTP_MCP=1` to expose the MCP server over Streamable HTTP (bearer-token auth) so a whole team can share one Grasp instance instead of each running their own stdio server.\n\n**Previously in v3.20.0:** Full security scanning suite — `grasp_vulnerabilities` covers **5 threat vectors** (OSV.dev dependency CVEs, NIST NVD container/runtime CVEs, local supply-chain integrity checks, Socket.dev behavioral analysis, and scheduled `grasp_vuln_watch` monitoring) with `skip_container` / `skip_socket` / `skip_integrity` fast-scan flags.\n\n**Previously in v3.19.0:** Full visual + UX parity between `team-dashboard.html` and `index.html` — teal brand sweep, SVG icons, 7-provider auth, mobile More menu, keyboard shortcut popover.\n\n**Previously in v3.18.0:** 9 new MCP tools (graph analytics + LLM-context), 11 graph export formats, TypeScript path-alias + Python import resolvers, Claude Code slash commands, token-reduction eval harness (3,241× on `got@v14`).\n\nTotal as of v3.21.0: **150 MCP tools · 8 Resources · 2 Prompts · 35 languages · 11 graph export formats · 10 graph views · multimodal knowledge graph · 19 themes**.\n\n---\n\n## What is Grasp?\n\n**Grasp** turns any GitHub or GitLab repository — cloud or self-hosted — or local codebase into an interactive architecture map in seconds. **150 MCP tools** (plus 8 Resources and 2 guided Prompts) expose the full analysis engine to Claude Code, Cursor, and any MCP-compatible agent.\n\n```\nPaste URL / Open Folder  →  AST Analysis Engine  →  Architecture Map + 150 MCP Tools\n```\n\n| | |\n|---|---|\n| **No installation** | Runs 100% in your browser — two HTML files, no build step |\n| **No data collection** | Your code never leaves your machine |\n| **No accounts** | Paste a URL and go |\n| **Works offline** | Analyse local folders without internet |\n| **35 languages** | JS/TS, Python, Go, Java, Rust, C/C++, C#, Ruby, Swift, Kotlin, Scala, Dart, Elixir, Erlang, Haskell, OCaml, F#, Clojure, Julia, Lua, R, Perl, Shell, PowerShell, Groovy, Zig, V, Nim, Crystal, VBA, Ada/SPARK, Vue, Svelte, PHP |\n| **150 MCP tools** | Dependency graphs, security, **OSV.dev SCA vulnerability scanning**, DORA, brain store, Kuzu graph schema v3, communities, ORM tracker, git change impact, architecture drift detection, test coverage gap map, org dashboard, PR impact action, MCP Resources/Prompts, `grasp setup` editor auto-config |\n| **11 AI providers** *(+ unlimited via routers)* | Direct: Anthropic Claude (3 models), OpenAI (GPT-4o + o-series), Google Gemini (3), Mistral (2), Groq (3), DeepSeek (chat + reasoner), Ollama (local), LM Studio (local), Custom OpenAI-compatible endpoint. Routers: OpenRouter (200+ models via slug) and Together AI (50+ open-source models). **Switchable mid-conversation**, **fully off by default** (chat panel closed = zero network calls), **API keys stored in `localStorage` only** — Grasp has no proxy or telemetry. |\n| **10 graph views** | Force graph, 3D, arch, treemap, matrix, tree (dendrogram), flow (sankey), bundle, cluster (disjoint), heatmap |\n| **Grasp Brain** | SQLite + Kuzu persistent store — index once, query instantly. FTS5 + 384D vector embeddings + Cypher graph queries |\n| **Supply chain signed** | SLSA Level 2 npm provenance + Cosign keyless Docker signing on every release |\n\n---\n\n## Who is Grasp for?\n\n| You are… | Grasp helps you… | Start with |\n|----------|------------------|------------|\n| **Tech lead** joining a new team | Map the codebase in 60s, find the riskiest hotspots, identify good first issues | `Try expressjs/express` chip → ISS tab + ACT tab |\n| **Engineering manager** | Track health across all team repos, see DORA metrics, identify bus-factor risks | `team-dashboard.html` |\n| **Open-source maintainer** | Generate a wiki, label good first issues, post PR impact comments | `grasp_wiki` + GitHub Action `grasp-pr-impact` |\n| **Security reviewer** | Spot hardcoded secrets, scan dependencies for CVEs, generate SBOM/SARIF | VULN tab + `grasp_sbom` + `grasp_sarif` |\n| **AI agent (Claude Code, Cursor, Copilot)** | Get sub-100-token repo orientation + token-budget-aware traversal | MCP server: `grasp_minimal_context` → `grasp_traverse` |\n| **Developer onboarding** | Get an ordered reading path, plain-English explanations of any file | `grasp_onboard` + `grasp_explain` |\n| **Refactoring contractor** | Plan migrations with topological ordering, preview renames, find duplicate code | `grasp_migration_plan` + `grasp_apply_refactor` |\n| **CTO evaluating tech debt** | Quantify debt in dev-days, flag legacy hotspots, justify rewrite budget | Health Score + Technical Debt + Org Dashboard |\n\n---\n\n## What makes Grasp different\n\nGrasp is intentionally additive to whatever static-analysis or graph tool you already use. The axes that matter:\n\n| Capability | Grasp |\n|-----------|-------|\n| Run on a stranger's repo without cloning | ✅ Paste URL → instant analysis in browser |\n| Zero install, zero account | ✅ Single HTML file, runs entirely in browser |\n| MCP-native — works with Claude Code, Cursor, Copilot, Continue, etc. | ✅ 150 tools, 8 Resources, 2 Prompts |\n| Supply-chain CVE scanning | ✅ OSV.dev across npm/PyPI/Go/Cargo/Maven |\n| 35 languages with native AST | ✅ Tree-sitter |\n| Local — your code never leaves your machine | ✅ Browser fetches direct; MCP runs as subprocess |\n| Persistent architecture intelligence | ✅ Brain store + Kuzu graph DB |\n| Multi-channel — Chrome/Firefox/Safari/VS Code/JetBrains/Docker/Raycast/Zed | ✅ 13 distribution channels |\n\n---\n\n## Screenshots\n\n### 🕸️ Dependency Graph — see exactly how files connect\n\n<img src=\"docs/screenshots/graph.png\" alt=\"Grasp dependency graph view\" width=\"100%\"/>\n\n### 🏛️ Architecture Diagram — your codebase by layer\n\n<img src=\"docs/screenshots/arch.png\" alt=\"Grasp architecture diagram view\" width=\"100%\"/>\n\n### 📦 Treemap — files sized by line count\n\n<img src=\"docs/screenshots/treemap.png\" alt=\"Grasp treemap view\" width=\"100%\"/>\n\n### 🏢 Team Dashboard — health across all your repos at a glance\n\n<img src=\"docs/screenshots/team-dashboard.png\" alt=\"Grasp team dashboard\" width=\"100%\"/>\n\n---\n\n## Quick Start\n\n### Option 1 — Browser (zero setup)\n\n```bash\ngit clone https://github.com/ashfordeOU/grasp.git\nopen index.html           # Main app\nopen team-dashboard.html  # Team Dashboard\n```\n\nNo build step. No `npm install`. **Two HTML files.**\n\n### Option 2 — CLI\n\n```bash\nnpm install -g grasp-mcp-server\n\ngrasp ./my-project        # Analyse a local folder\ngrasp facebook/react      # Analyse a GitHub repo\ngrasp .                   # Analyse current directory\ngrasp . --watch           # Live mode — browser reloads on every file save\ngrasp . --timeline        # Time-travel — last 30 commits as a scrubber\ngrasp . --report          # Terminal-only report + JSON output\ngrasp . --format=sarif    # Export SARIF for GitHub Code Scanning\ngrasp . --pr-comment      # Print GitHub PR comment markdown to stdout\ngrasp . --check           # Enforce grasp.yml architecture rules (CI gate)\n```\n\n### Option 3 — IDE Extensions\n\n| IDE | Install |\n|-----|---------|\n| **VS Code** | [Install (.vsix)](https://github.com/ashfordeOU/grasp/releases/latest) — download `grasp-vscode-3.21.0.vsix` and run **Extensions: Install from VSIX…** (`Cmd+Shift+P`) |\n| **JetBrains** | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/31362-grasp--code-architecture-visualizer) — search **Grasp** in Settings → Plugins |\n| **Raycast** | [Raycast Store](https://www.raycast.com/ashfordeOU/grasp) — or search **Grasp** in the Raycast extension store |\n| **Zed** | [Zed Extensions](https://zed.dev/extensions?query=grasp) — or search **grasp** in Zed → Extensions |\n\n### Option 4 — Browser Extension\n\n| Browser | Install |\n|---------|---------|\n| **Chrome** | [Chrome Web Store](https://chromewebstore.google.com/detail/grasp-%E2%80%94-code-architecture/pipmlammandfhfbodllcjolgeolkhapj) |\n| **Firefox** | [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/grasp-code-architecture) — ID: `grasp@ashforde.org` |\n| **Safari** | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) — see [sideload instructions](#safari-sideload) |\n\nA floating **Grasp** button appears on every GitHub and GitLab page. Supports self-hosted GitLab, GitHub Enterprise, and any custom host via on-demand permission grants.\n\n---\n\n### Distribution at a Glance\n\nEvery tagged release auto-publishes to all channels:\n\n| Channel | Status | Link |\n|---------|--------|------|\n| **npm** (`grasp-mcp-server`) | [![npm](https://img.shields.io/npm/v/grasp-mcp-server?style=flat-square)](https://www.npmjs.com/package/grasp-mcp-server) | `npm install -g grasp-mcp-server` |\n| **MCP Registry** | Listed | [modelcontextprotocol.io](https://mcpregistry.com) |\n| **Docker** (`ghcr.io/ashfordeou/grasp`) | [![ghcr](https://img.shields.io/badge/ghcr.io-latest-blue?style=flat-square)](https://github.com/ashfordeOU/grasp/pkgs/container/grasp) | `docker pull ghcr.io/ashfordeou/grasp:latest` |\n| **VS Code** | `.vsix` on Releases | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases/latest) |\n| **JetBrains** | Marketplace | [Plugin ID 31362](https://plugins.jetbrains.com/plugin/31362-grasp--code-architecture-visualizer) |\n| **Raycast** | Store (PR per release) | [raycast.com/ashfordeOU/grasp](https://www.raycast.com/ashfordeOU/grasp) |\n| **Zed** | Extension (PR per release) | [zed.dev/extensions](https://zed.dev/extensions?query=grasp) |\n| **Chrome** | Web Store | [CWS listing](https://chromewebstore.google.com/detail/grasp-%E2%80%94-code-architecture/pipmlammandfhfbodllcjolgeolkhapj) |\n| **Firefox** | AMO (listed) | [addons.mozilla.org](https://addons.mozilla.org/firefox/addon/grasp-code-architecture) |\n| **Safari** | Sideload (macOS 13+) | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) |\n| **GitLab bot image** | `ghcr.io/ashfordeou/grasp-gitlab-bot` | Auto-pushed per release |\n| **GitLab tunnel agent** | Binary on Releases | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) |\n| **GitHub Release** | Signed + checksums | [Releases page](https://github.com/ashfordeOU/grasp/releases) |\n\n### AI-tool integrations *(Grasp called by your assistant via MCP or extension)*\n\n| AI tool | How to install | Notes |\n|---------|----------------|-------|\n| **Claude Code** | `claude mcp add grasp -- npx -y grasp-mcp-server` | Native MCP — all 150 tools + 8 Resources + 2 Prompts |\n| **Cursor** | Add `grasp-mcp-server` to `~/.cursor/mcp.json` | Native MCP |\n| **Cline / Roo Code / Kilo Code** | MCP config in VS Code settings | Native MCP |\n| **Windsurf** | MCP config | Native MCP |\n| **Codex / OpenCode / Trae / Droid** | MCP config | Native MCP — `grasp setup` auto-configures all of them |\n| **Gemini CLI / Grok CLI** | MCP config | Native MCP |\n| **GitHub Copilot Chat** | Install `grasp-copilot-extension` | Copilot calls Grasp via the Copilot Extension API — `@grasp` mention in chat |\n| **Continue** | `continue-provider` package | Grasp as a Continue context provider |\n| **Amazon Q Developer** | `amazon-q-plugin` | Grasp surfaces in Q's chat |\n| **GPT Actions / Custom GPTs** | `gpt-actions` package | Grasp exposed as REST for OpenAI Actions schema |\n| **Aider / Sweep / any tool** | Use the `grasp-mcp-server` npm package | Tool-agnostic stdio JSON-RPC |\n\n<details>\n<summary id=\"safari-sideload\">🧭 Safari Sideload Instructions</summary>\n\n```bash\ncurl -sL https://github.com/ashfordeOU/grasp/releases/latest/download/grasp-safari-extension.zip \\\n  -o /tmp/grasp-safari.zip \\\n  && unzip -q /tmp/grasp-safari.zip -d /tmp/grasp-safari \\\n  && mv /tmp/grasp-safari/Grasp.app /Applications/ \\\n  && open /Applications/Grasp.app\n```\n\nThen in Safari: **Settings → Extensions → enable Grasp**. If it doesn't appear, enable **Safari → Develop → Allow Unsigned Extensions** first.\n\n</details>\n\n---\n\n## How It Works\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│  Input                                                            │\n│  github.com/owner/repo  ·  gitlab.com/ns/proj  ·  ./local/path   │\n└────────────────────────────────┬─────────────────────────────────┘\n                                 ▼\n┌──────────────────────────────────────────────────────────────────┐\n│  Analysis Pipeline  (mcp/src/)                                    │\n│                                                                   │\n│  1. scan        file enumeration + gitignore                      │\n│  2. parse       tree-sitter AST · 35 languages · 19 native        │\n│  3. resolvers   tsconfig path-alias · Jedi-style Python imports   │\n│  4. routes      HTTP route detection (Express/FastAPI/Gin)        │\n│  5. tools       MCP/gRPC tool definition detection                │\n│  6. orm         ORM query tracking (Prisma/TypeORM/Sequelize/SA)  │\n│  7. scope       3-tier call resolver  (0.95 → 0.90 → 0.50)       │\n│  8. types       cross-file type propagation  (Kahn topo-sort)     │\n│  9. coverage    test-file detection → TESTS/COVERS edges (v3)     │\n│ 10. communities Louvain community detection on import graph       │\n│ 11. processes   BFS execution-flow tracing from entry points      │\n│ 12. analytics   degree centrality · Brandes betweenness ·         │\n│                 surprising-edge rarity · knowledge-gap detection  │\n│ 13. vulns       OSV.dev SCA scan (npm/PyPI/Go/Cargo/Maven)        │\n└───────────┬──────────────────────────┬────────────────────────────┘\n            │                          │\n    ┌───────▼─────────┐    ┌───────────▼─────────────────┐\n    │  Browser App    │    │   MCP Server (CLI)           │\n    │  index.html     │    │   grasp-mcp-server           │\n    │                 │    │                              │\n    │ 10 graph views  │    │ 150 tools · 8 Resources      │\n    │ 16 color modes  │    │ 2 guided Prompts             │\n    │ AI Chat (11p)   │    │ Brain + Kuzu Schema v3       │\n    │ Ask Grasp       │    │ Hybrid search (BM25+vector)  │\n    │ Coverage overlay│    │ Graph analytics (5 tools)    │\n    │ VULN tab        │    │ LLM-context (4 tools)        │\n    │ Try-it chips    │    │ Graph exports (GraphML /     │\n    │ Token indicator │    │   Cypher / Obsidian)         │\n    │ Snapshot URLs   │    │ Slash commands (3 in         │\n    │ Compare modal   │    │   .claude/commands/)         │\n    │ Mid-fetch retry │    │ grasp setup (5 editors)      │\n    │ Mobile touch    │    │ grasp vulns / drift / org    │\n    └─────────────────┘    └──────────────────────────────┘\n```\n\n**Analysis flow (v3.18.0):** the pipeline is additive — phase 12 (graph analytics) runs after the dependency graph is built and produces the data backing `grasp_hub_nodes`, `grasp_bridge_nodes`, `grasp_surprising_connections`, `grasp_knowledge_gaps`, and `grasp_suggested_questions`. Phase 13 only runs when a manifest (`package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`) is present. Both browser and MCP server share the exact same pipeline output via the `~/.grasp/brain.db` + `~/.grasp/graph/` pair so a CLI `grasp index` and a browser analyze of the same repo are interchangeable.\n\n---\n\n## Visualizations\n\n### Graph Types\n\n| View | Description |\n|------|-------------|\n| 🕸️ **Graph** | Force-directed dependency graph — drag, zoom, multi-select |\n| 🔮 **3D Graph** | Three-dimensional force graph — rotate, pan, zoom |\n| 🏛️ **Arch** | Layer-by-layer architecture diagram |\n| 📦 **Treemap** | Files sized by line count, grouped by folder |\n| 📊 **Matrix** | Adjacency matrix showing all dependencies |\n| 🌳 **Tree** | Hierarchical cluster dendrogram |\n| 🌊 **Flow** | Folder-level Sankey dependency flow |\n| 🎯 **Bundle** | Circular layout with arc-based connections |\n| 🔮 **Cluster** | Separated force graphs per folder |\n\n### Color Modes\n\n| Mode | What it shows |\n|------|---------------|\n| 📁 **Folder** | Directory structure |\n| 🏗️ **Layer** | Architectural layer (UI, Services, Utils, etc.) |\n| 🔥 **Churn** | Commit frequency — red = most-changed hot spots |\n| ⚡ **Complexity** | Cyclomatic complexity (green → yellow → red) |\n| 💥 **Blast** | Blast radius impact for a selected file |\n| 🌊 **Depth** | Max brace-nesting depth |\n| 🔎 **Dup** | Duplicate code density — red = many clones |\n| 👤 **Owner** | Top contributor — spot bus-factor risks |\n| 🐛 **Issues** | Linked GitHub Issues per file |\n| 🧪 **Coverage** | Test coverage — highlight untested files |\n| 📦 **Bundle** | Bundle size contribution |\n| 🌐 **API Surface** | Public-facing file exposure |\n| ⚡ **Runtime** | Actual call frequency from a live trace |\n| 🔒 **Safety** | Safety gate coverage (green = gated, red = ungated) |\n| 🧪 **Boundary** | Research/production boundary drift |\n| 🧪 **Eval Coverage** | Coverage from eval/test scripts |\n\n---\n\n## Code Intelligence\n\n### 📊 Health Score\nInstant **A–F grade** based on dead code, circular dependencies, coupling metrics, and security issues. Displayed as a score (0–100) with a visual bar.\n\n### 🔐 Security Scanner\nAutomatic detection of hardcoded secrets & API keys, SQL injection risks, dangerous `eval()` usage, and debug statements left in production.\n\n### 🛡️ Dependency & Container Security Scanner *(v3.17.0, expanded v3.20.0)*\nFive-layer security scan via `grasp_vulnerabilities`:\n\n- **Dependency CVEs** — declared deps (npm/PyPI/Go/Cargo/Maven) vs [OSV.dev](https://osv.dev) public CVE database. Resolves pinned versions from lockfiles. Severity-classified with CVSS scores and fix-version suggestions. Health score deducts –5 per critical and –3 per high.\n- **Container/Runtime CVEs** — parses `Dockerfile` (`FROM image:tag`), `docker-compose*.yml`, and CI workflow YAML for pinned image versions, then queries [NIST NVD](https://nvd.nist.gov). Set `GRASP_NVD_API_KEY` for higher rate limits.\n- **Supply-chain integrity** — local checks (no network): npm lockfile sha512 `integrity` field coverage, `go.sum` alongside `go.mod`, `Cargo.lock` alongside `Cargo.toml`, `--hash=` pinning in `requirements.txt`.\n- **Behavioral analysis** — [Socket.dev](https://socket.dev) free API scans npm packages for malware, supply-chain risk, and install-script signals (up to 50 packages per scan).\n- **Scheduled monitoring** — `grasp_vuln_watch` MCP tool: `start`/`stop`/`status`/`history` actions; periodic re-scans via `setInterval`; persists scan history + CVE diffs in `brain.db`.\n\nNew `grasp vulns <path>` CLI exits 1 on critical/high findings (CI-friendly). **100% client-side** — all API requests go directly from your machine to the respective services, never through a Grasp server.\n\n### 🧩 Pattern Detection\nIdentifies Singleton, Factory, Observer/Event patterns, React hooks, and anti-patterns (God Objects, high coupling) — automatically.\n\n### 💥 Blast Radius Analysis\n*\"If I change this file, what breaks?\"* — select any file and see every downstream file that would be affected, highlighted on the graph.\n\n### 🔥 Activity Heatmap\nColors files by commit frequency. Works for GitHub repos (via API) and **local repos** (via `git log` — no internet required).\n\n### 🔎 Duplicate & Similarity Detection\nThe **Dup** color mode highlights files with exact or near-duplicate code. The `grasp_similarity` MCP tool returns ranked duplicate clusters for targeted refactoring.\n\n### 🧠 Multimodal Knowledge Graph *(MCP server)*\nBuild a queryable knowledge graph from your codebase **and** external documents, then ask natural-language questions with cited answers. Runs entirely inside the Node MCP server — **not** the browser app.\n\n`grasp_ingest` parses PDF, DOCX, XLSX, HTML, images (OCR), audio/video (local Whisper via `@xenova/transformers` + ffmpeg), YouTube, and URLs; heavy parsers are optional, lazy-loaded dependencies. Entities and relations are tagged **EXTRACTED** vs **INFERRED** with source locators and persisted to SQLite `kg.db`; retrieval is hybrid BM25 + vector. A **local-first** multi-LLM layer auto-detects Ollama before any cloud key and falls back to a deterministic engine that needs zero credentials (Anthropic / OpenAI / Gemini / DeepSeek / Kimi / Azure / Bedrock / Ollama). The whole server can optionally be shared across a team over HTTP (`GRASP_HTTP_MCP=1`, optional `GRASP_HTTP_API_KEY`, port `7333`, `/health`).\n\n| MCP Tool | Description |\n|----------|-------------|\n| `grasp_ingest` | Ingest a file, URL, or media source (PDF/DOCX/XLSX/HTML/image OCR/audio/video/YouTube) into the knowledge graph |\n| `grasp_kg_ask` | Natural-language Q&A over the graph with inline source citations (hybrid BM25 + vector) |\n| `grasp_kg_trace` | BFS path-tracing between two entities |\n| `grasp_kg_explain` | Explain an entity, its relations, and whether each fact was EXTRACTED or INFERRED |\n| `grasp_kg_stats` | Graph statistics — entity/relation counts, hubs, and god-nodes |\n| `grasp_kg_export` | Export the graph as Cypher, GraphML, JSON, or Mermaid |\n| `grasp_llm_status` | Report the active LLM provider and any detected local models (Ollama), including deterministic-fallback state |\n\n### 👥 Code Ownership\nTop contributors per file from git history, with line-percentage breakdowns. One-click jump to GitHub Blame.\n\n### 📋 PR Impact Analysis\nPaste a PR URL to see which files it touches and calculate the blast radius of proposed changes before merging.\n\n### 💰 Technical Debt Quantification\nConverts every architectural issue into developer-hours using configurable estimates — circular dep = 4h, god file = 16h, critical security = 8h — with a coupling multiplier. Shown in the health panel and Team Dashboard.\n\n### 🔗 Shareable Embeds\nClick `⋯ → 🔗 Embed` for a ready-to-paste `<iframe>`, README badge, React snippet, and direct link — share live health reports in docs, wikis, or dashboards.\n\n### 🎯 Connection Confidence Scoring *(v3.16.0)*\nEvery cross-file connection is scored 0–1: explicit static imports = 1.0, same-folder = 0.8, cross-folder inferred = 0.6, low-frequency = 0.4. The force graph overlays confidence as edge opacity — use the slider in ⚙ settings to filter out low-confidence edges.\n\n### 🔍 Graph Query Modal *(v3.16.0)*\nClick the 🔍 toolbar button to search files, functions, and edges in-browser without leaving the graph. Matches update live — click any file result to jump to it on the graph.\n\n### ƒ() Function-Level Canvas *(v3.16.0)*\nToggle the `ƒ()` button to switch the force graph from file-level to function-level nodes — see individual function call relationships, capped at 300 nodes for performance.\n\n### 🗄️ DB Coupling Tab *(v3.16.0)*\nThe right panel **🗄️ DB** tab scans file content for ORM patterns (Django, TypeORM, raw SQL), mapping which files reference which tables. Instantly spot god-tables and high-coupling files.\n\n### 🎯 Good First Issues Tab *(v3.16.0)*\nThe **🎯 GFI** tab surfaces isolated, low-complexity, untested files — ideal contribution targets for new engineers or AI coding agents.\n\n### 🔐 PII Detection & Security Subcategories *(v3.16.0)*\nThe Security tab now has subcategory pills — **ALL / SECRETS / INJECTION / PII / EVAL** — to filter findings. The PII pill scans file content for email, phone, SSN, credit card, and API key patterns in source files.\n\n### 📸 Architecture Drift Detection *(v3.17.0)*\nSnapshot your codebase architecture and detect drift over time — automatically.\n\n```bash\ngrasp snapshot ./my-project --name before-refactor\n# ... make changes ...\ngrasp drift ./my-project          # exits 1 if drift is CRITICAL (CI-friendly)\n```\n\n| MCP Tool | Description |\n|----------|-------------|\n| `grasp_snapshot` | Save current health score, coupling metrics, circular deps, and top-10 hotspots as a named snapshot |\n| `grasp_diff_snapshots` | Compare any two snapshots — returns health delta, new circular deps, files whose coupling increased >20%, drift level (STABLE / DEGRADED / CRITICAL) |\n\nSnapshots are stored in `~/.grasp/brain.db` and persist across analysis sessions.\n\n### 🧪 Test Coverage Gap Map *(v3.17.0)*\nFind the functions most likely to cause production incidents — highest call count, zero test coverage.\n\n```bash\ngrasp_coverage_gaps  # via MCP — returns uncovered_functions sorted by call_count DESC\n```\n\nThe dependency graph gains a **🧪 Coverage overlay** toggle — uncovered functions render in red, partially-covered in amber, covered in green. Coverage is estimated by static analysis: Grasp detects test files (`*.test.*`, `*.spec.*`, `test_*`, `*_test.*`) and traces which source functions they reference.\n\n| MCP Tool | Description |\n|----------|-------------|\n| `grasp_coverage_gaps` | Returns `uncovered_functions` (sorted by call count), `risky_uncovered` (high churn + no tests), `coverage_by_module` per directory, and `overall_coverage_estimate` |\n\n### 🏢 Org-Level Dashboard *(v3.17.0)*\nAnalyse an entire GitHub organisation in one command:\n\n```bash\ngrasp org my-github-org --token ghp_xxx --format html   # Self-contained HTML dashboard\ngrasp org my-github-org --format json                   # CI-consumable JSON\ngrasp org my-github-org --format md                     # Markdown for wikis\n```\n\nAggregates health grades, security findings, most-churned files, and language distribution across all repos (up to 500, 5 concurrent). The HTML output embeds Chart.js inline — no external dependencies.\n\n| MCP Tool | Description |\n|----------|-------------|\n| `grasp_org_summary` | Analyse up to 20 top repos in an org — returns aggregate health grade, grade distribution, total security findings by severity, top churned files, language breakdown |\n\n### 🤖 PR Impact GitHub Action *(v3.17.0)*\nAdd automated architectural impact analysis to every pull request:\n\n```yaml\n# .github/workflows/grasp-pr-impact.yml\n- uses: ashfordeOU/grasp/.github/actions/grasp-pr-impact@main\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    min-risk-to-comment: LOW      # LOW / MEDIUM / HIGH / CRITICAL\n    fail-on-risk: CRITICAL        # fail the CI check at this risk level\n```\n\nThe action posts a structured PR comment showing:\n- **Risk badge** (LOW / MEDIUM / HIGH / CRITICAL) with colour coding\n- Changed files with function-level blast radius\n- Affected execution processes (with step counts)\n- Suggested reviewers from `git blame` (top 2 contributors per affected file)\n- Test coverage gaps: which changed functions have no test file touching them\n\n---\n\n## AI Chat — 11 Providers + Routers\n\nBuilt-in AI assistant that knows your entire codebase. Ask *\"why is auth.ts a hotspot?\"*, *\"which files are safest to refactor?\"*, or *\"explain the security issues in this call chain\"* — answers reference your live dependency graph, security findings, and architectural layers.\n\n| Provider | Models |\n|----------|--------|\n| **Anthropic** | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 |\n| **OpenAI** | GPT-4o, GPT-4o mini, o3-mini, o1 |\n| **Google Gemini** | Gemini 2.0 Flash, 1.5 Pro, 1.5 Flash |\n| **Mistral** | Mistral Small, Mistral Large |\n| **Groq** | Llama 3.3 70B, 3.1 8B, Gemma 2 9B |\n| **DeepSeek** | DeepSeek Chat, DeepSeek Reasoner |\n| **OpenRouter** | Any model slug (100+ models via one key) |\n| **Together AI** | Any model slug |\n| **Ollama** | Local models (no key needed) |\n| **LM Studio** | Local models on any port |\n| **Custom** | Any OpenAI-compatible base URL |\n\n**Features:**\n- Multi-turn conversation memory — persisted in `localStorage` across page refreshes\n- Selected-file context — layer, functions, complexity, and issues injected automatically when a file is selected\n- Rich codebase context — top 80 files with metadata, all issues, security findings, circular deps, layer breakdown\n- Markdown rendering with syntax-highlighted code blocks\n- API key stays in your browser only, never sent anywhere except the chosen provider\n\n---\n\n## Grasp Brain — Persistent Architecture Intelligence *(v3.16.0)*\n\nGrasp Brain combines two persistent stores that work together:\n\n- **SQLite Brain** (`~/.grasp/brain.db`) — file metadata, coupling, security, and issue index. Includes a FTS5 full-text index over functions and an in-process 384D vector embedding store (Xenova/all-MiniLM-L6-v2 — no cloud dependency). Index once, query instantly.\n- **Kuzu Graph DB** (`~/.grasp/graph/`) — native graph database with Cypher query support. Stores the full function call graph, file imports, and type relationships as a traversable property graph.\n\nIndex once, then query instantly — no re-analysis needed. Every function is tagged with the execution processes it participates in (BFS from entry points), so search results include a `processes[]` field grouping matches by flow.\n\n### How it works\n\n```\ngrasp index ./my-project    →  analysis stored in ~/.grasp/brain.db\ngrasp context src/api.ts    →  instant file context from the stored index\ngrasp diff ./my-project     →  compare current state vs stored baseline\ngrasp daemon ./my-project   →  watch for changes, re-index automatically\n```\n\n### CLI Subcommands\n\n```bash\ngrasp index <path>           # Analyse and persist a repo to the brain\ngrasp context <src> <file>   # Get rich context for any file\ngrasp setup [path]           # Install hooks in Claude Code / Cursor / Windsurf\ngrasp diff <path>            # Compare current analysis vs brain baseline\ngrasp daemon <path>          # Watch directory and auto-reindex on changes\ngrasp drift [path]           # Snapshot + diff vs last snapshot; exits 1 on CRITICAL (CI-friendly)\ngrasp org <github-org>       # Org-level dashboard (--format json|html|md --token ghp_xxx)\ngrasp vulns [path]           # OSV.dev dependency vulnerability scan\n```\n\n### Ask Grasp — Natural Language Architecture Queries\n\nBoth the browser app (Ask Grasp panel) and `grasp_ask` MCP tool support plain-English questions about your codebase. `grasp_ask` recognises structural intents directly; for open-ended queries it falls back to **hybrid semantic search** — BM25 full-text + 384D vector embeddings merged with Reciprocal Rank Fusion.\n\nFor pure semantic search without the question-answering layer, use `grasp_search` directly — results include a `processes[]` field showing which execution flows each match belongs to.\n\n| Question | What you get |\n|----------|--------------|\n| *\"What are the most complex files?\"* | Files ranked by cyclomatic complexity |\n| *\"Show me coupling hotspots\"* | Files with highest combined fan-in + fan-out |\n| *\"Any security issues?\"* | All security findings across the codebase |\n| *\"What's the blast radius of auth.ts?\"* | Full transitive impact list |\n| *\"What layer handles data access?\"* | Layer breakdown with file examples |\n| *\"What's the overall grade?\"* | Health score, grade, issue summary |\n| *\"Which files have the most churn?\"* | Commit frequency ranking |\n| *\"Are there circular dependencies?\"* | Cycle list with severity |\n\n### Registry — All Indexed Repos\n\n`grasp_registry_list` and `grasp_registry_status` expose the full Brain index:\n\n```bash\n# Via MCP\ngrasp_registry_list          # all repos: health grade, files, functions, active sessions\ngrasp_registry_status        # aggregate: indexed count, session count, grade distribution\n\n# Via HTTP (when MCP server runs with --http)\ncurl http://localhost:7332/api/v1/registry\n```\n\nThe Team Dashboard **🗂️ Registry panel** auto-fetches this on load — no session_id needed.\n\n### Arch Diff\n\n`grasp diff` (and `grasp_arch_diff` MCP tool) compares your current codebase against the stored brain baseline and surfaces:\n- Grade degradations (files that got worse: A→B, B→C, etc.)\n- Health score delta\n- New security issues introduced since baseline\n\n### Editor Hooks (`grasp setup`)\n\nDetects `.claude/`, `.cursor/`, `.windsurf/` in your repo and installs a pre-tool-use hook that automatically gives your AI coding assistant codebase context before every action. Also writes `CLAUDE.md` and `AGENTS.md` with architecture summaries.\n\n---\n\n## Team & Collaboration\n\n### 🏢 Team Dashboard\n\nTrack health across multiple repos in one view. Add any public (or private, with a token) GitHub repo and see:\n\n- Health score, grade, files, issues, circular deps, security findings, architectural layers\n- **Pattern count, Env var issues, Feature flag count** — new v3.13.0 columns\n- **DORA metrics mini-card** — Deploy Frequency, Lead Time, Change Fail Rate, MTTR per repo (expandable row)\n- **🗂️ Registry panel** — all Brain-indexed repos with live health grades and session status\n- Commit activity (7d / 30d) and CI status (✅/❌/⏳)\n- Commit velocity sparkline, Technical debt in developer-days\n- Export the full table as **CSV or JSON**. Open local folders with 📁 Open Folder (File System Access API).\n\n### 🔄 Live Team Collaboration\n\nGrasp's CLI hosts a real-time collaboration server for your whole team:\n\n```bash\nnpx grasp --host=0.0.0.0 --room-secrets=backend:pass1,frontend:pass2\n#   → main app:       http://server-ip:7331/\n#   → team dashboard: http://server-ip:7331/dashboard\n#   → health check:   http://server-ip:7331/api/health\n```\n\n- **WebSocket sync** — workspace changes propagate to all connected team members instantly\n- **Named rooms** — `?sync_room=backend-team` isolates each team's workspace\n- **Presence indicators** — see who's online in the Sync panel\n- **Share links** — ⎘ Copy team link or 👁 Copy read-only link\n- **Read-only mode** — `?readonly=1` for observers\n- **Password protection** — `--room-secrets=room:password`\n- **REST API** — `GET /api/health` · `GET /api/rooms` · `GET/PUT /api/workspace/:room`\n\n> **LAN hosting:** anyone on the same network accesses `http://server-ip:7331/dashboard` — no cloud needed.\n\n### 🏢 Monorepo & Workspace Support\n\nGrasp automatically detects sub-packages in monorepos (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`). A **Workspace** sidebar lets you filter to a single package — all graphs, treemaps, and metrics update instantly.\n\n### ⏮️ Time-Travel Architecture Scrubber\n\nRun `grasp . --timeline` to load your last 30 git commits as a scrubber panel. Drag the slider to any commit — changed nodes glow yellow on the graph so you can watch your architecture evolve over time.\n\n### 📡 Live Watch Mode\n\nRun `grasp . --watch` for a local dev server with real-time SSE sync. Every file save reloads the browser graph automatically — a `LIVE` badge appears while connected.\n\n---\n\n## Industry Verticals\n\n### ✈️ Aerospace / Safety-Critical\n\n| Feature | Description |\n|---------|-------------|\n| **Requirement Traceability** | Upload a requirements CSV — Grasp scans for `@REQ-NNN` tags and shows coverage %, missing, and unspecified files. One-click compliance matrix export. |\n| **MISRA / Safety Mode** | `⋯ → 🔧 Safety Mode` — detect MISRA C/C++ and Ada violations: dynamic allocation after init, recursive calls, `goto`, `abort()`/`exit()`. |\n| **DO-178C / ECSS Certification Export** | One-click certification evidence package: inventory, traceability matrix, complexity, MISRA violations, security findings — JSON and printable HTML. |\n| **Anomaly Investigation** | Select file → 🔍 Anomaly Investigation — callers, callees, transitive blast radius, recent commits, security in call path, plain-English summary. |\n| **Software Reuse Assessor** | Traffic-light matrix across Interface Compatibility, Dependencies, Safety Level, Architecture Fitness, Security, Complexity. |\n| **Cross-language Call Graph** | Ada→C `pragma Import`, Python `ctypes`/`cffi`, JS→WASM boundaries. |\n| **Heritage Software Genealogy** | Overlay an origin-mission manifest, identify zero-delta certification shortcuts. |\n| **ICD Mapper** | Match Interface Control Document entries to exported functions, flag unimplemented interfaces. |\n| **ECSS-E-ST-40C Compliance** | Check DI-01, DI-04, DI-07, DI-10, DI-15 compliance requirements. |\n\n### 🧠 AI Research\n\n| Feature | Description |\n|---------|-------------|\n| **Safety Constraint Tracer** | Mark safety gates (filters, sanitizers) — trace every entry→output path and flag any that bypass all gates. New **Safety** color mode. |\n| **Research/Production Boundary** | Define research vs production folders — flags production files that import from research code. |\n| **Jupyter Notebook Support** | `.ipynb` in the dependency graph — extracts code cells, parses imports, flags reproducibility issues. |\n| **Training Run Diff** | Upload two YAML/JSON configs — diff hyperparameters and find which files read each changed key. |\n| **Eval Coverage Map** | Auto-detects eval scripts and traces which model/training code they exercise. Safety gates with no eval coverage flagged as critical. |\n| **ML Pipeline DAG** | Detects PyTorch, TensorFlow, JAX, HuggingFace patterns — renders Data→Model→Training→Eval→Checkpoint DAG. |\n\n### 🏢 Enterprise\n\n| Feature | Description |\n|---------|-------------|\n| **SBOM Generation** | CycloneDX 1.4 or SPDX 2.3 JSON for npm, pip, Cargo, Go modules. Optional CVE enrichment via OSV API. |\n| **DORA Metrics** | Deployment Frequency, Lead Time, Change Failure Rate, MTTR from GitHub Actions. Elite/High/Medium/Low classification. |\n| **AI-Powered ADR Generation** | One-click MADR-format Architecture Decision Records using codebase context + optional PR diff. |\n| **PII Data Flow Tracer** | BFS from user-marked PII source files — shows all downstream consumers. |\n| **Separation of Duties** | Detects files that both initiate and approve transactions (SOX/FDA compliance). |\n| **Regulatory Change Impact** | Keywords-to-blast-radius for GDPR/HIPAA/SOX/PCI-DSS article changes. |\n| **Finance / Trading** | Latency hotspot detection — blocking I/O, GC pressure, lock contention, allocation in loops. |\n| **Financial Model Risk** | Hardcoded parameters, missing NaN checks, division without zero-guard. |\n\n---\n\n## Token-Reduction Benchmark *(v3.18.0)*\n\n`scripts/eval-token-reduction.mjs` is a benchmark harness that measures how many tokens an LLM saves by querying `grasp_minimal_context` instead of reading every source file. It clones 6 OSS repos (express, flask, gin, got, lodash, axios), computes naive total-token cost, calls Grasp, and reports the reduction factor.\n\n```bash\n# Build the MCP server first\ncd mcp && node build.mjs && cd ..\n\n# Run the full benchmark (clones 6 repos to /tmp/grasp-eval, ~5 minutes)\nnode scripts/eval-token-reduction.mjs\n\n# Or just one repo\nnode scripts/eval-token-reduction.mjs --only got\n```\n\nOutputs to `docs/benchmarks/token-reduction.{md,json}`. Verified end-to-end on `got@v14.0.0`: 113,438 → 35 tokens.\n\n---\n\n## For AI Agents — MCP Server\n\nGrasp ships a **Model Context Protocol (MCP) server** that exposes the full analysis engine as callable tools for Claude Code, Cursor, and any MCP-compatible agent.\n\n### Setup\n\n```bash\n# Install\nnpm install -g grasp-mcp-server\n\n# Or run without installing\nnpx grasp-mcp-server\n```\n\nAdd to `~/.claude/claude_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"grasp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"grasp-mcp-server\"]\n    }\n  }\n}\n```\n\nWorks with GitHub repos and local directories. See [`mcp/README.md`](mcp/README.md) for GitLab, Docker, and self-hosted options.\n\n### Claude Code Slash Commands *(v3.18.0)*\n\nThree pre-built slash commands ship in `.claude/commands/` so any Claude Code workspace can invoke Grasp's most common flows in one step:\n\n| Command | What it does |\n|---------|-------------|\n| `/grasp:build-graph` | Runs `grasp_analyze` on the current dir + `grasp_minimal_context` for a sub-100-token orientation |\n| `/grasp:review-delta` | Detects changes since base branch and produces a risk-scored impact report |\n| `/grasp:review-pr` | Full PR review composing detect_changes + suggested_questions + surprising_connections + knowledge_gaps |\n\nEach command is a markdown file with allowed-tools and template body. Edit them in-repo to customize.\n\n### Tools Reference\n\n> **Tier legend:** Most tools work after a single `grasp_analyze`. Some require an indexed Brain (run `grasp_brain_index` first) — flagged in their description with phrases like \"from the brain index\". A few make outbound network calls: GitHub Issues / DORA / CI status / deps.dev (`grasp_issues`, `grasp_jira_issues`, `grasp_dora`, `grasp_ci_status`, `grasp_deps_dev`) need a token; `grasp_vulnerabilities` queries OSV.dev, NIST NVD, and Socket.dev; `grasp_vuln_watch` runs scheduled re-scans; `grasp_adr` calls the AI provider you configure. `grasp_apply_refactor` and `grasp_rename` are the only tools that *write* to disk (off by default — `dry_run` / `apply: false` is the default).\n\n**Core Analysis**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_analyze` | Full analysis of any repo or local path — returns `session_id` for follow-up queries |\n| `grasp_sessions` | List active sessions (persist 7 days, survive restarts) |\n| `grasp_diff` | Compare two snapshots — what changed between analyses? |\n| `grasp_watch` | Re-analyse a directory and diff against a prior run |\n| `grasp_rules_check` | Run `grasp.yml` architecture rules and report violations |\n| `grasp_config_check` | Validate a session against architecture rules — returns violations |\n\n**File & Code Intelligence**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_file_deps` | What does this file depend on? |\n| `grasp_dependents` | What breaks if I change this file? |\n| `grasp_cycles` | Are there circular dependencies? |\n| `grasp_architecture` | What layers does this codebase have? |\n| `grasp_hotspots` | Which files are riskiest to touch? |\n| `grasp_metrics` | Lines, complexity, fan-in/fan-out per file |\n| `grasp_find_path` | How does file A connect to file B? |\n| `grasp_patterns` | What design patterns are in use? |\n| `grasp_unused` | Dead code — defined but never called |\n| `grasp_explain` | Plain-English explanation of any file or function |\n| `grasp_refactor` | Step-by-step refactor plan for a file or session |\n| `grasp_suggest` | Ranked refactoring suggestions by effort-to-impact ratio |\n| `grasp_onboard` | Ordered reading path for new engineers entering a codebase area |\n| `grasp_types` | Type annotation coverage — prioritises high fan-in files lacking types |\n| `grasp_similarity` | Ranked duplicate clusters and code-clone groups |\n| `grasp_stale` | Active but abandoned files — low churn, high fan-in, no test counterpart |\n| `grasp_change_risk` | Risk score 0–100 for a set of changed files |\n\n**Security & Compliance**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_security` | Hardcoded secrets, injection risks, dangerous patterns |\n| `grasp_sbom` | SBOM in CycloneDX 1.4 or SPDX 2.3 JSON |\n| `grasp_sarif` | SARIF 2.1.0 export for GitHub Code Scanning |\n| `grasp_license` | Dependency licenses — flags copyleft and unknown |\n| `grasp_pii_trace` | BFS trace from PII source files to all consumers |\n| `grasp_duties` | Separation of duties — files that both initiate and approve |\n| `grasp_reg_impact` | Regulatory change blast radius (GDPR/HIPAA/SOX/PCI-DSS) |\n| `grasp_env_vars` | All env var reads — flags undocumented and test-only vars |\n| `grasp_feature_flags` | All feature flag reads (LaunchDarkly, GrowthBook, env-var flags) |\n\n**Team & DevOps**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_pr_comment` | Generate PR health comment with blast radius for changed files |\n| `grasp_pr_review` | Post inline review comments on a GitHub PR at high-severity lines |\n| `grasp_commits` | Commit counts for last 7d and 30d |\n| `grasp_ci_status` | Latest GitHub Actions run — passing/failing/in-progress |\n| `grasp_dora` | DORA metrics — Deployment Frequency, Lead Time, CFR, MTTR |\n| `grasp_adr` | AI-powered MADR-format Architecture Decision Record |\n| `grasp_embed` | Generate iframe, README badge, React snippet for sharing |\n| `grasp_timeline` | Last N commits with per-commit changed files + co-change matrix |\n| `grasp_contributors` | Per-file ownership, bus-factor, top contributors |\n| `grasp_coverage` | Test coverage overlay — which files lack tests? |\n| `grasp_issues` | Map GitHub Issues to the files they mention |\n| `grasp_jira_issues` | Map Jira issues to source files via project key |\n| `grasp_service_graph` | Service-level dependency graph from OTEL / custom trace JSON |\n| `grasp_deps_dev` | Ecosystem dependents via deps.dev — how many packages depend on this repo |\n\n**Brain / Intelligence** *(v3.16.0)*\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_brain_index` | Analyse and persist a repo to the local SQLite brain |\n| `grasp_brain_status` | What's indexed in the brain and when? |\n| `grasp_context` | Rich file context — layer, complexity, coupling, security, dependents, dependencies |\n| `grasp_arch_diff` | Compare current state vs brain baseline — detect degradations |\n| `grasp_ask` | Ask a natural language question about your architecture |\n\n**Graph Core** *(Kuzu — v3.16.0)*\n\n| Tool | What it does |\n|------|-------------|\n| `graph_query` | Run read-only Cypher queries against the persistent function/file call graph |\n| `call_chain` | Trace caller and callee chains for any function, up to configurable depth |\n| `type_propagation` | Find all functions sharing a return type and their call neighbors |\n| `function_graph` | Render a Mermaid / DOT / JSON subgraph centred on any named function |\n\n**Advanced Analysis**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_dead_packages` | npm deps in `package.json` but never imported |\n| `grasp_runtime_calls` | Merge a live runtime trace with static edges — actual hot paths |\n| `grasp_db_coupling` | ORM/SQL-to-table coupling map — god tables, high-coupling files |\n| `grasp_migration_plan` | Phased topologically-ordered plan for replacing a package/module |\n| `grasp_api_surface` | Unified API surface from OpenAPI, GraphQL, Express/FastAPI routes |\n| `grasp_events` | Event emitters and subscribers — orphaned emits, ghost subscriptions |\n| `grasp_perf` | N+1 queries, synchronous I/O, JSON serialization in loops |\n| `grasp_bundle` | Bundle size treemap — largest files by size category |\n| `grasp_dep_impact` | Impact of upgrading a dependency across all files |\n| `grasp_cross_repo` | Compare two sessions — shared files, diverged functions |\n| `grasp_diagram` | Generate Mermaid flowchart or C4 diagrams from the dependency graph |\n\n**Aerospace / Safety-Critical Vertical**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_req_trace` | Requirement traceability — scan `@REQ-NNN` tags against a CSV |\n| `grasp_anomaly` | Anomaly investigation — BFS blast radius, security in call chain, plain-English summary |\n| `grasp_reuse` | Software reuse assessor — Red/Amber/Green compatibility matrix |\n| `grasp_safety_trace` | Safety constraint tracer — finds paths that bypass all safety gates |\n| `grasp_multilang` | Cross-language call graph (Ada→C, Python→C, JS→WASM) |\n| `grasp_heritage` | Heritage software genealogy — zero-delta certification shortcuts |\n| `grasp_icd` | ICD mapper — match Interface Control Document entries to code |\n| `grasp_ecss` | ECSS-E-ST-40C compliance checker (DI-01, DI-04, DI-07, DI-10, DI-15) |\n\n**AI Research Vertical**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_run_diff` | Training run diff — changed hyperparameters and affected code |\n| `grasp_eval_coverage` | Eval coverage map — safety gates with no eval coverage flagged critical |\n\n**Multi-Repo / Platform**\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_org_graph` | Org-level multi-repo dependency graph with inter-repo edges |\n| `grasp_api_diff` | Breaking API change detector — removed/changed exported symbols |\n| `grasp_plugins` | Extension-point map — plugin interfaces, hook points, strategy patterns |\n| `grasp_semver` | Semantic versioning enforcer — validate semver bump for the change set |\n| `grasp_abi_diff` | ABI/API stability checker — stability score 0–100 |\n| `grasp_subsystems` | Kernel/OS subsystem boundary map |\n| `grasp_kconfig` | Kconfig/build-time conditional analysis — CONFIG_* usage map |\n| `grasp_irq` | IRQ/interrupt dependency graph — blocking calls, allocation in handlers |\n| `grasp_patch_impact` | Patch series impact analyzer — rank patches by blast radius + complexity |\n| `grasp_good_first_issues` | Good first issue generator — isolated, low-complexity, untested files |\n| `grasp_api_stability` | API stability score (0–100) between two sessions |\n| `grasp_fork_diff` | Fork divergence analysis — diverged/identical/fork-only files |\n| `grasp_latency` | Finance/trading latency hotspot detection |\n| `grasp_model_risk` | Financial model risk auditor |\n\n**Code Intelligence *(v3.16.0)***\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_diff_symbols` | Map `git diff` hunks to functions — blast radius of a PR before merge |\n| `grasp_exec_flow` | BFS execution flow from any entry point with STEP_IN_PROCESS edges + Mermaid chart |\n| `grasp_skillmd` | Auto-generate `SKILL.md` / `CLAUDE.md` snippet from the analysis session |\n| `grasp_hooks` | Generate `.claude/settings.json` PostToolUse hook + `.cursor/rules/grasp.mdc` |\n| `grasp_mro` | Method Resolution Order — C3 linearization (Python), MRO for Ruby/Java hierarchies |\n| `grasp_communities` | Leiden/Louvain community detection — identify bounded contexts and microservice candidates |\n| `grasp_contracts` | Multi-repo contract analysis — provider exports vs consumer usage, violations + coverage % |\n\n**Analysis Intelligence *(v3.16.0)***\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_confidence` | Score every cross-file connection 0–1 (explicit import=1.0, same-folder=0.8, cross-folder=0.6, low-freq=0.4) |\n| `grasp_wiki` | Auto-generate a markdown wiki: index.md + per-folder pages + api.md sorted by caller count |\n| `grasp_registry_list` | List all Brain-indexed repos with health grade, file/function counts, and active session IDs |\n| `grasp_registry_status` | Registry health: indexed count, session count, grade distribution |\n| `grasp_resolve_receiver` | Resolve the concrete class for every class method — what `self`/`this` refers to across Python, JS, Java, Ruby |\n\n**Semantic Search, Rename & Routes *(v3.16.0)***\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_search` | Hybrid semantic search — BM25 FTS5 + 384D vector embeddings (Xenova/all-MiniLM-L6-v2) merged with Reciprocal Rank Fusion. Results include `processes[]` grouping by execution flow. Supports `@groupName` fan-out across multiple repos |\n| `grasp_rename` | Graph-aware whole-codebase symbol rename using brain store edges to find every reference. `apply: false` (default) returns a dry-run diff; `apply: true` writes changes to disk |\n| `grasp_route_map` | Scan for HTTP route definitions (Express/Fastify/Hono, FastAPI/Flask, Gin) — maps each route to its handler function with file location |\n| `grasp_api_impact` | Given a route or handler name, returns all callers, downstream services, and blast radius using brain graph edges |\n| `grasp_tool_map` | Scan for MCP tool definitions (`server.tool` / `server.registerTool`) and gRPC service definitions — returns a service contract map |\n| `grasp_shape_check` | For any function, traces parameter types and return types across all call sites from the brain index; flags call-site mismatches |\n| `grasp_group_add` | Add a repo source to a named group in `~/.grasp/groups.json` for multi-repo `@groupName` fan-out |\n| `grasp_group_list` | List all named groups and their member repos from `~/.grasp/groups.json` |\n\n**Graph Intelligence *(v3.16.0)***\n\n| Tool | Description |\n|---|---|\n| `grasp_graph_schema` | Kuzu schema v3 introspection — node/edge table definitions (File, Function, Class, Interface, Method, Constructor, TestFile + 12 edge types including TESTS and COVERS) with live row counts |\n| `grasp_type_propagation` | Cross-file type inference via Kahn topological sort over import graph; returns top inferred types with confidence 0–1 |\n| `grasp_orm_map` | ORM query tracker — Prisma, TypeORM, Sequelize, SQLAlchemy; results grouped by model with call sites, operations, frequency |\n| `grasp_detect_changes` | Git diff → symbol impact: changed files, affected functions, impacted process flows, risk level `LOW`/`MEDIUM`/`HIGH`/`CRITICAL` |\n| `grasp_generate_agents_md` | Generate rich AGENTS.md from brain session — functional communities, execution processes, health grade, top issues |\n| `grasp_generate_skills` | Per-community `.claude/skills/generated/<community>.md` files — key files, entry points, cross-area deps |\n\n**Graph Analytics & LLM Context** *(v3.18.0)*\n\n| Tool | What it does |\n|------|-------------|\n| `grasp_hub_nodes` | Top-N most connected files by fan-in + fan-out (degree centrality) |\n| `grasp_bridge_nodes` | Brandes betweenness centrality. Auto-samples 100 sources for repos > 500 nodes |\n| `grasp_surprising_connections` | Rare cross-layer edges flagged by frequency-weighted rarity |\n| `grasp_knowledge_gaps` | Isolated files, untested hotspots, weak communities |\n| `grasp_suggested_questions` | Auto-generated 5–10 review questions composing all of the above |\n| `grasp_minimal_context` | Sub-100-token repo orientation — the LLM's first call |\n| `grasp_traverse` | Token-budget-aware BFS from any starting node |\n| `grasp_semantic_search` | Cosine similarity over function signatures via @xenova/transformers |\n| `grasp_apply_refactor` | Executes rename ops with dry_run preview default |\n| `grasp_architecture_overview` | Combined community + hub + review-question report |\n| `grasp_export_graphml` | yEd / Gephi-compatible GraphML XML export |\n| `grasp_export_cypher` | Neo4j CREATE statements that reproduce the graph |\n| `grasp_export_obsidian` | `.canvas` JSON for Obsidian Canvas with per-layer column layout |\n| `grasp_export_dot` | Graphviz DOT (`digraph`) — clusters per layer, edge counts, renders on GitHub |\n| `grasp_export_mermaid` | Mermaid `graph LR` — inline-renders on GitHub, GitLab, Notion, Obsidian |\n| `grasp_export_d2` | Terrastruct D2 — `direction: right` with layer containers, render via `d2` CLI |\n| `grasp_export_plantuml` | PlantUML class diagram — works in Confluence, Jira, IntelliJ, VS Code |\n| `grasp_export_dgml` | Visual Studio Directed Graph XML — opens natively in VS Architecture window |\n| `grasp_export_gexf` | Gephi-native GEXF 1.3 with layer/lines/complexity/churn node attributes |\n| `grasp_export_drawio` | draw.io / diagrams.net XML — grid layout, editable in app.diagrams.net |\n| `grasp_export_csv` | Three-sheet CSV bundle: files, connections, issues — opens in any spreadsheet |\n\n**MCP Resources *(v3.16.0)*** — 8 live `grasp://` URIs for direct resource access: `grasp://repos` · `grasp://setup` · `grasp://repo/{id}/context` · `grasp://repo/{id}/clusters` · `grasp://repo/{id}/processes` · `grasp://repo/{id}/schema` · `grasp://repo/{id}/cluster/{name}` · `grasp://repo/{id}/process/{name}`\n\n**MCP Prompts *(v3.16.0)*** — `detect_impact` (changes → symbols → processes → risk → test scope) · `generate_map` (repos → analyze → diagram → communities → wiki)\n\n---\n\n## CI/CD Integration\n\n### GitHub Actions — Automatic PR Comments\n\n```yaml\n# .github/workflows/grasp.yml\nname: Grasp Health Check\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\njobs:\n  health:\n    uses: ashfordeOU/grasp/.github/workflows/grasp-health.yml@main\n```\n\nThe workflow posts and updates a comment on every PR:\n\n| Metric | Value |\n|--------|-------|\n| **Health Score** | `████████░░` **82/100** |\n| **Grade** | 🟢 **A** |\n| **Files** | 142 (891 functions) |\n| **Architecture Issues** | 3 |\n| **Circular Deps** | 0 ✓ |\n| **Security** | 0 ✓ |\n| **Changed Files** | 5 code files in this PR |\n\n### Architecture Rules (`grasp.yml`)\n\n```yaml\nrules:\n  - min_health_score: 70       # fail CI if score drops below 70\n  - max_blast_radiu",
  "bytes": 60000,
  "sha": "8388810210254d2edc734e68a65fa100d6182d7fde442dc045d2082e2a6e7d0c",
  "repo_slug": "ashfordeou/grasp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ashfordeou_grasp_e2f9f0ea/readme"
}