grasp

<div align="center"> <img src="grasp-social-v2.png" alt="Grasp — Code Architecture Suite" width="100%"/> > [English](README.md) · [हिन्दी](README.hi.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [简体中文](README.zh.md) <br/> <br/> <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> <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> <a href="LICENSE" target="_blank"><img src="https://img.shields.io/badge/license-ELv2-4d9fff?style=flat-square" alt="License"/></a> <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> <br/> **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** <br/> <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> &nbsp; <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> <br/> <a href="https://ashfordeou.github.io/grasp" target="_blank">🌐 Browser App</a> &nbsp;·&nbsp; <a href="https://www.npmjs.com/package/grasp-mcp-server" target="_blank">📦 MCP Server</a> &nbsp;·&nbsp; <a href="https://github.com/ashfordeOU/grasp/issues" target="_blank">🐛 Report Bug</a> &nbsp;·&nbsp; <a href="https://github.com/ashfordeOU/grasp/issues" target="_blank">✨ Request Feature</a> &nbsp;·&nbsp; <a href="https://ashfordeou.github.io/grasp/docs/privacy.html" target="_blank">🔒 Privacy</a> </div> --- ## What's New in v3.21.0 **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). **+3 native AST languages** — Bash, Elixir, and Julia take tree-sitter-backed function extraction, call counting, and complexity scoring to **19 languages**. **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. **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. **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. **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`). Total 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**. --- ## What is Grasp? **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. ``` Paste URL / Open Folder → AST Analysis Engine → Architecture Map + 150 MCP Tools ``` | | | |---|---| | **No installation** | Runs 100% in your browser — two HTML files, no build step | | **No data collection** | Your code never leaves your machine | | **No accounts** | Paste a URL and go | | **Works offline** | Analyse local folders without internet | | **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 | | **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 | | **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. | | **10 graph views** | Force graph, 3D, arch, treemap, matrix, tree (dendrogram), flow (sankey), bundle, cluster (disjoint), heatmap | | **Grasp Brain** | SQLite + Kuzu persistent store — index once, query instantly. FTS5 + 384D vector embeddings + Cypher graph queries | | **Supply chain signed** | SLSA Level 2 npm provenance + Cosign keyless Docker signing on every release | --- ## Who is Grasp for? | You are… | Grasp helps you… | Start with | |----------|------------------|------------| | **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 | | **Engineering manager** | Track health across all team repos, see DORA metrics, identify bus-factor risks | `team-dashboard.html` | | **Open-source maintainer** | Generate a wiki, label good first issues, post PR impact comments | `grasp_wiki` + GitHub Action `grasp-pr-impact` | | **Security reviewer** | Spot hardcoded secrets, scan dependencies for CVEs, generate SBOM/SARIF | VULN tab + `grasp_sbom` + `grasp_sarif` | | **AI agent (Claude Code, Cursor, Copilot)** | Get sub-100-token repo orientation + token-budget-aware traversal | MCP server: `grasp_minimal_context` → `grasp_traverse` | | **Developer onboarding** | Get an ordered reading path, plain-English explanations of any file | `grasp_onboard` + `grasp_explain` | | **Refactoring contractor** | Plan migrations with topological ordering, preview renames, find duplicate code | `grasp_migration_plan` + `grasp_apply_refactor` | | **CTO evaluating tech debt** | Quantify debt in dev-days, flag legacy hotspots, justify rewrite budget | Health Score + Technical Debt + Org Dashboard | --- ## What makes Grasp different Grasp is intentionally additive to whatever static-analysis or graph tool you already use. The axes that matter: | Capability | Grasp | |-----------|-------| | Run on a stranger's repo without cloning | ✅ Paste URL → instant analysis in browser | | Zero install, zero account | ✅ Single HTML file, runs entirely in browser | | MCP-native — works with Claude Code, Cursor, Copilot, Continue, etc. | ✅ 150 tools, 8 Resources, 2 Prompts | | Supply-chain CVE scanning | ✅ OSV.dev across npm/PyPI/Go/Cargo/Maven | | 35 languages with native AST | ✅ Tree-sitter | | Local — your code never leaves your machine | ✅ Browser fetches direct; MCP runs as subprocess | | Persistent architecture intelligence | ✅ Brain store + Kuzu graph DB | | Multi-channel — Chrome/Firefox/Safari/VS Code/JetBrains/Docker/Raycast/Zed | ✅ 13 distribution channels | --- ## Screenshots ### 🕸️ Dependency Graph — see exactly how files connect <img src="docs/screenshots/graph.png" alt="Grasp dependency graph view" width="100%"/> ### 🏛️ Architecture Diagram — your codebase by layer <img src="docs/screenshots/arch.png" alt="Grasp architecture diagram view" width="100%"/> ### 📦 Treemap — files sized by line count <img src="docs/screenshots/treemap.png" alt="Grasp treemap view" width="100%"/> ### 🏢 Team Dashboard — health across all your repos at a glance <img src="docs/screenshots/team-dashboard.png" alt="Grasp team dashboard" width="100%"/> --- ## Quick Start ### Option 1 — Browser (zero setup) ```bash git clone https://github.com/ashfordeOU/grasp.git open index.html # Main app open team-dashboard.html # Team Dashboard ``` No build step. No `npm install`. **Two HTML files.** ### Option 2 — CLI ```bash npm install -g grasp-mcp-server grasp ./my-project # Analyse a local folder grasp facebook/react # Analyse a GitHub repo grasp . # Analyse current directory grasp . --watch # Live mode — browser reloads on every file save grasp . --timeline # Time-travel — last 30 commits as a scrubber grasp . --report # Terminal-only report + JSON output grasp . --format=sarif # Export SARIF for GitHub Code Scanning grasp . --pr-comment # Print GitHub PR comment markdown to stdout grasp . --check # Enforce grasp.yml architecture rules (CI gate) ``` ### Option 3 — IDE Extensions | IDE | Install | |-----|---------| | **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`) | | **JetBrains** | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/31362-grasp--code-architecture-visualizer) — search **Grasp** in Settings → Plugins | | **Raycast** | [Raycast Store](https://www.raycast.com/ashfordeOU/grasp) — or search **Grasp** in the Raycast extension store | | **Zed** | [Zed Extensions](https://zed.dev/extensions?query=grasp) — or search **grasp** in Zed → Extensions | ### Option 4 — Browser Extension | Browser | Install | |---------|---------| | **Chrome** | [Chrome Web Store](https://chromewebstore.google.com/detail/grasp-%E2%80%94-code-architecture/pipmlammandfhfbodllcjolgeolkhapj) | | **Firefox** | [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/grasp-code-architecture) — ID: `grasp@ashforde.org` | | **Safari** | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) — see [sideload instructions](#safari-sideload) | A 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. --- ### Distribution at a Glance Every tagged release auto-publishes to all channels: | Channel | Status | Link | |---------|--------|------| | **npm** (`grasp-mcp-server`) | [](https://www.npmjs.com/package/grasp-mcp-server) | `npm install -g grasp-mcp-server` | | **MCP Registry** | Listed | [modelcontextprotocol.io](https://mcpregistry.com) | | **Docker** (`ghcr.io/ashfordeou/grasp`) | [](https://github.com/ashfordeOU/grasp/pkgs/container/grasp) | `docker pull ghcr.io/ashfordeou/grasp:latest` | | **VS Code** | `.vsix` on Releases | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases/latest) | | **JetBrains** | Marketplace | [Plugin ID 31362](https://plugins.jetbrains.com/plugin/31362-grasp--code-architecture-visualizer) | | **Raycast** | Store (PR per release) | [raycast.com/ashfordeOU/grasp](https://www.raycast.com/ashfordeOU/grasp) | | **Zed** | Extension (PR per release) | [zed.dev/extensions](https://zed.dev/extensions?query=grasp) | | **Chrome** | Web Store | [CWS listing](https://chromewebstore.google.com/detail/grasp-%E2%80%94-code-architecture/pipmlammandfhfbodllcjolgeolkhapj) | | **Firefox** | AMO (listed) | [addons.mozilla.org](https://addons.mozilla.org/firefox/addon/grasp-code-architecture) | | **Safari** | Sideload (macOS 13+) | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) | | **GitLab bot image** | `ghcr.io/ashfordeou/grasp-gitlab-bot` | Auto-pushed per release | | **GitLab tunnel agent** | Binary on Releases | [GitHub Releases](https://github.com/ashfordeOU/grasp/releases) | | **GitHub Release** | Signed + checksums | [Releases page](https://github.com/ashfordeOU/grasp/releases) | ### AI-tool integrations *(Grasp called by your assistant via MCP or extension)* | AI tool | How to install | Notes | |---------|----------------|-------| | **Claude Code** | `claude mcp add grasp -- npx -y grasp-mcp-server` | Native MCP — all 150 tools + 8 Resources + 2 Prompts | | **Cursor** | Add `grasp-mcp-server` to `~/.cursor/mcp.json` | Native MCP | | **Cline / Roo Code / Kilo Code** | MCP config in VS Code settings | Native MCP | | **Windsurf** | MCP config | Native MCP | | **Codex / OpenCode / Trae / Droid** | MCP config | Native MCP — `grasp setup` auto-configures all of them | | **Gemini CLI / Grok CLI** | MCP config | Native MCP | | **GitHub Copilot Chat** | Install `grasp-copilot-extension` | Copilot calls Grasp via the Copilot Extension API — `@grasp` mention in chat | | **Continue** | `continue-provider` package | Grasp as a Continue context provider | | **Amazon Q Developer** | `amazon-q-plugin` | Grasp surfaces in Q's chat | | **GPT Actions / Custom GPTs** | `gpt-actions` package | Grasp exposed as REST for OpenAI Actions schema | | **Aider / Sweep / any tool** | Use the `grasp-mcp-server` npm package | Tool-agnostic stdio JSON-RPC | <details> <summary id="safari-sideload">🧭 Safari Sideload Instructions</summary> ```bash curl -sL https://github.com/ashfordeOU/grasp/releases/latest/download/grasp-safari-extension.zip \ -o /tmp/grasp-safari.zip \ && unzip -q /tmp/grasp-safari.zip -d /tmp/grasp-safari \ && mv /tmp/grasp-safari/Grasp.app /Applications/ \ && open /Applications/Grasp.app ``` Then in Safari: **Settings → Extensions → enable Grasp**. If it doesn't appear, enable **Safari → Develop → Allow Unsigned Extensions** first. </details> --- ## How It Works ``` ┌──────────────────────────────────────────────────────────────────┐ │ Input │ │ github.com/owner/repo · gitlab.com/ns/proj · ./local/path │ └────────────────────────────────┬─────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Analysis Pipeline (mcp/src/) │ │ │ │ 1. scan file enumeration + gitignore │ │ 2. parse tree-sitter AST · 35 languages · 19 native │ │ 3. resolvers tsconfig path-alias · Jedi-style Python imports │ │ 4. routes HTTP route detection (Express/FastAPI/Gin) │ │ 5. tools MCP/gRPC tool definition detection │ │ 6. orm ORM query tracking (Prisma/TypeORM/Sequelize/SA) │ │ 7. scope 3-tier call resolver (0.95 → 0.90 → 0.50) │ │ 8. types cross-file type propagation (Kahn topo-sort) │ │ 9. coverage test-file detection → TESTS/COVERS edges (v3) │ │ 10. communities Louvain community detection on import graph │ │ 11. processes BFS execution-flow tracing from entry points │ │ 12. analytics degree centrality · Brandes betweenness · │ │ surprising-edge rarity · knowledge-gap detection │ │ 13. vulns OSV.dev SCA scan (npm/PyPI/Go/Cargo/Maven) │ └───────────┬──────────────────────────┬────────────────────────────┘ │ │ ┌───────▼─────────┐ ┌───────────▼─────────────────┐ │ Browser App │ │ MCP Server (CLI) │ │ index.html │ │ grasp-mcp-server │ │ │ │ │ │ 10 graph views │ │ 150 tools · 8 Resources │ │ 16 color modes │ │ 2 guided Prompts │ │ AI Chat (11p) │ │ Brain + Kuzu Schema v3 │ │ Ask Grasp │ │ Hybrid search (BM25+vector) │ │ Coverage overlay│ │ Graph analytics (5 tools) │ │ VULN tab │ │ LLM-context (4 tools) │ │ Try-it chips │ │ Graph exports (GraphML / │ │ Token indicator │ │ Cypher / Obsidian) │ │ Snapshot URLs │ │ Slash commands (3 in │ │ Compare modal │ │ .claude/commands/) │ │ Mid-fetch retry │ │ grasp setup (5 editors) │ │ Mobile touch │ │ grasp vulns / drift / org │ └─────────────────┘ └──────────────────────────────┘ ``` **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. --- ## Visualizations ### Graph Types | View | Description | |------|-------------| | 🕸️ **Graph** | Force-directed dependency graph — drag, zoom, multi-select | | 🔮 **3D Graph** | Three-dimensional force graph — rotate, pan, zoom | | 🏛️ **Arch** | Layer-by-layer architecture diagram | | 📦 **Treemap** | Files sized by line count, grouped by folder | | 📊 **Matrix** | Adjacency matrix showing all dependencies | | 🌳 **Tree** | Hierarchical cluster dendrogram | | 🌊 **Flow** | Folder-level Sankey dependency flow | | 🎯 **Bundle** | Circular layout with arc-based connections | | 🔮 **Cluster** | Separated force graphs per folder | ### Color Modes | Mode | What it shows | |------|---------------| | 📁 **Folder** | Directory structure | | 🏗️ **Layer** | Architectural layer (UI, Services, Utils, etc.) | | 🔥 **Churn** | Commit frequency — red = most-changed hot spots | | ⚡ **Complexity** | Cyclomatic complexity (green → yellow → red) | | 💥 **Blast** | Blast radius impact for a selected file | | 🌊 **Depth** | Max brace-nesting depth | | 🔎 **Dup** | Duplicate code density — red = many clones | | 👤 **Owner** | Top contributor — spot bus-factor risks | | 🐛 **Issues** | Linked GitHub Issues per file | | 🧪 **Coverage** | Test coverage — highlight untested files | | 📦 **Bundle** | Bundle size contribution | | 🌐 **API Surface** | Public-facing file exposure | | ⚡ **Runtime** | Actual call frequency from a live trace | | 🔒 **Safety** | Safety gate coverage (green = gated, red = ungated) | | 🧪 **Boundary** | Research/production boundary drift | | 🧪 **Eval Coverage** | Coverage from eval/test scripts | --- ## Code Intelligence ### 📊 Health Score Instant **A–F grade** based on dead code, circular dependencies, coupling metrics, and security issues. Displayed as a score (0–100) with a visual bar. ### 🔐 Security Scanner Automatic detection of hardcoded secrets & API keys, SQL injection risks, dangerous `eval()` usage, and debug statements left in production. ### 🛡️ Dependency & Container Security Scanner *(v3.17.0, expanded v3.20.0)* Five-layer security scan via `grasp_vulnerabilities`: - **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. - **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. - **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`. - **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). - **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`. New `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. ### 🧩 Pattern Detection Identifies Singleton, Factory, Observer/Event patterns, React hooks, and anti-patterns (God Objects, high coupling) — automatically. ### 💥 Blast Radius Analysis *"If I change this file, what breaks?"* — select any file and see every downstream file that would be affected, highlighted on the graph. ### 🔥 Activity Heatmap Colors files by commit frequency. Works for GitHub repos (via API) and **local repos** (via `git log` — no internet required). ### 🔎 Duplicate & Similarity Detection The **Dup** color mode highlights files with exact or near-duplicate code. The `grasp_similarity` MCP tool returns ranked duplicate clusters for targeted refactoring. ### 🧠 Multimodal Knowledge Graph *(MCP server)* Build 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. `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`). | MCP Tool | Description | |----------|-------------| | `grasp_ingest` | Ingest a file, URL, or media source (PDF/DOCX/XLSX/HTML/image OCR/audio/video/YouTube) into the knowledge graph | | `grasp_kg_ask` | Natural-language Q&A over the graph with inline source citations (hybrid BM25 + vector) | | `grasp_kg_trace` | BFS path-tracing between two entities | | `grasp_kg_explain` | Explain an entity, its relations, and whether each fact was EXTRACTED or INFERRED | | `grasp_kg_stats` | Graph statistics — entity/relation counts, hubs, and god-nodes | | `grasp_kg_export` | Export the graph as Cypher, GraphML, JSON, or Mermaid | | `grasp_llm_status` | Report the active LLM provider and any detected local models (Ollama), including deterministic-fallback state | ### 👥 Code Ownership Top contributors per file from git history, with line-percentage breakdowns. One-click jump to GitHub Blame. ### 📋 PR Impact Analysis Paste a PR URL to see which files it touches and calculate the blast radius of proposed changes before merging. ### 💰 Technical Debt Quantification Converts 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. ### 🔗 Shareable Embeds Click `⋯ → 🔗 Embed` for a ready-to-paste `<iframe>`, README badge, React snippet, and direct link — share live health reports in docs, wikis, or dashboards. ### 🎯 Connection Confidence Scoring *(v3.16.0)* Every 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. ### 🔍 Graph Query Modal *(v3.16.0)* Click 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. ### ƒ() Function-Level Canvas *(v3.16.0)* Toggle 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. ### 🗄️ DB Coupling Tab *(v3.16.0)* The 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. ### 🎯 Good First Issues Tab *(v3.16.0)* The **🎯 GFI** tab surfaces isolated, low-complexity, untested files — ideal contribution targets for new engineers or AI coding agents. ### 🔐 PII Detection & Security Subcategories *(v3.16.0)* The 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. ### 📸 Architecture Drift Detection *(v3.17.0)* Snapshot your codebase architecture and detect drift over time — automatically. ```bash grasp snapshot ./my-project --name before-refactor # ... make changes ... grasp drift ./my-project # exits 1 if drift is CRITICAL (CI-friendly) ``` | MCP Tool | Description | |----------|-------------| | `grasp_snapshot` | Save current health score, coupling metrics, circular deps, and top-10 hotspots as a named snapshot | | `grasp_diff_snapshots` | Compare any two snapshots — returns health delta, new circular deps, files whose coupling increased >20%, drift level (STABLE / DEGRADED / CRITICAL) | Snapshots are stored in `~/.grasp/brain.db` and persist across analysis sessions. ### 🧪 Test Coverage Gap Map *(v3.17.0)* Find the functions most likely to cause production incidents — highest call count, zero test coverage. ```bash grasp_coverage_gaps # via MCP — returns uncovered_functions sorted by call_count DESC ``` The 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. | MCP Tool | Description | |----------|-------------| | `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` | ### 🏢 Org-Level Dashboard *(v3.17.0)* Analyse an entire GitHub organisation in one command: ```bash grasp org my-github-org --token ghp_xxx --format html # Self-contained HTML dashboard grasp org my-github-org --format json # CI-consumable JSON grasp org my-github-org --format md # Markdown for wikis ``` Aggregates 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. | MCP Tool | Description | |----------|-------------| | `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 | ### 🤖 PR Impact GitHub Action *(v3.17.0)* Add automated architectural impact analysis to every pull request: ```yaml # .github/workflows/grasp-pr-impact.yml - uses: ashfordeOU/grasp/.github/actions/grasp-pr-impact@main with: github-token: ${{ secrets.GITHUB_TOKEN }} min-risk-to-comment: LOW # LOW / MEDIUM / HIGH / CRITICAL fail-on-risk: CRITICAL # fail the CI check at this risk level ``` The action posts a structured PR comment showing: - **Risk badge** (LOW / MEDIUM / HIGH / CRITICAL) with colour coding - Changed files with function-level blast radius - Affected execution processes (with step counts) - Suggested reviewers from `git blame` (top 2 contributors per affected file) - Test coverage gaps: which changed functions have no test file touching them --- ## AI Chat — 11 Providers + Routers Built-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. | Provider | Models | |----------|--------| | **Anthropic** | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 | | **OpenAI** | GPT-4o, GPT-4o mini, o3-mini, o1 | | **Google Gemini** | Gemini 2.0 Flash, 1.5 Pro, 1.5 Flash | | **Mistral** | Mistral Small, Mistral Large | | **Groq** | Llama 3.3 70B, 3.1 8B, Gemma 2 9B | | **DeepSeek** | DeepSeek Chat, DeepSeek Reasoner | | **OpenRouter** | Any model slug (100+ models via one key) | | **Together AI** | Any model slug | | **Ollama** | Local models (no key needed) | | **LM Studio** | Local models on any port | | **Custom** | Any OpenAI-compatible base URL | **Features:** - Multi-turn conversation memory — persisted in `localStorage` across page refreshes - Selected-file context — layer, functions, complexity, and issues injected automatically when a file is selected - Rich codebase context — top 80 files with metadata, all issues, security findings, circular deps, layer breakdown - Markdown rendering with syntax-highlighted code blocks - API key stays in your browser only, never sent anywhere except the chosen provider --- ## Grasp Brain — Persistent Architecture Intelligence *(v3.16.0)* Grasp Brain combines two persistent stores that work together: - **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. - **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. Index 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. ### How it works ``` grasp index ./my-project → analysis stored in ~/.grasp/brain.db grasp context src/api.ts → instant file context from the stored index grasp diff ./my-project → compare current state vs stored baseline grasp daemon ./my-project → watch for changes, re-index automatically ``` ### CLI Subcommands ```bash grasp index <path> # Analyse and persist a repo to the brain grasp context <src> <file> # Get rich context for any file grasp setup [path] # Install hooks in Claude Code / Cursor / Windsurf grasp diff <path> # Compare current analysis vs brain baseline grasp daemon <path> # Watch directory and auto-reindex on changes grasp drift [path] # Snapshot + diff vs last snapshot; exits 1 on CRITICAL (CI-friendly) grasp org <github-org> # Org-level dashboard (--format json|html|md --token ghp_xxx) grasp vulns [path] # OSV.dev dependency vulnerability scan ``` ### Ask Grasp — Natural Language Architecture Queries Both 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. For 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. | Question | What you get | |----------|--------------| | *"What are the most complex files?"* | Files ranked by cyclomatic complexity | | *"Show me coupling hotspots"* | Files with highest combined fan-in + fan-out | | *"Any security issues?"* | All security findings across the codebase | | *"What's the blast radius of auth.ts?"* | Full transitive impact list | | *"What layer handles data access?"* | Layer breakdown with file examples | | *"What's the overall grade?"* | Health score, grade, issue summary | | *"Which files have the most churn?"* | Commit frequency ranking | | *"Are there circular dependencies?"* | Cycle list with severity | ### Registry — All Indexed Repos `grasp_registry_list` and `grasp_registry_status` expose the full Brain index: ```bash # Via MCP grasp_registry_list # all repos: health grade, files, functions, active sessions grasp_registry_status # aggregate: indexed count, session count, grade distribution # Via HTTP (when MCP server runs with --http) curl http://localhost:7332/api/v1/registry ``` The Team Dashboard **🗂️ Registry panel** auto-fetches this on load — no session_id needed. ### Arch Diff `grasp diff` (and `grasp_arch_diff` MCP tool) compares your current codebase against the stored brain baseline and surfaces: - Grade degradations (files that got worse: A→B, B→C, etc.) - Health score delta - New security issues introduced since baseline ### Editor Hooks (`grasp setup`) Detects `.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. --- ## Team & Collaboration ### 🏢 Team Dashboard Track health across multiple repos in one view. Add any public (or private, with a token) GitHub repo and see: - Health score, grade, files, issues, circular deps, security findings, architectural layers - **Pattern count, Env var issues, Feature flag count** — new v3.13.0 columns - **DORA metrics mini-card** — Deploy Frequency, Lead Time, Change Fail Rate, MTTR per repo (expandable row) - **🗂️ Registry panel** — all Brain-indexed repos with live health grades and session status - Commit activity (7d / 30d) and CI status (✅/❌/⏳) - Commit velocity sparkline, Technical debt in developer-days - Export the full table as **CSV or JSON**. Open local folders with 📁 Open Folder (File System Access API). ### 🔄 Live Team Collaboration Grasp's CLI hosts a real-time collaboration server for your whole team: ```bash npx grasp --host=0.0.0.0 --room-secrets=backend:pass1,frontend:pass2 # → main app: http://server-ip:7331/ # → team dashboard: http://server-ip:7331/dashboard # → health check: http://server-ip:7331/api/health ``` - **WebSocket sync** — workspace changes propagate to all connected team members instantly - **Named rooms** — `?sync_room=backend-team` isolates each team's workspace - **Presence indicators** — see who's online in the Sync panel - **Share links** — ⎘ Copy team link or 👁 Copy read-only link - **Read-only mode** — `?readonly=1` for observers - **Password protection** — `--room-secrets=room:password` - **REST API** — `GET /api/health` · `GET /api/rooms` · `GET/PUT /api/workspace/:room` > **LAN hosting:** anyone on the same network accesses `http://server-ip:7331/dashboard` — no cloud needed. ### 🏢 Monorepo & Workspace Support Grasp 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. ### ⏮️ Time-Travel Architecture Scrubber Run `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. ### 📡 Live Watch Mode Run `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. --- ## Industry Verticals ### ✈️ Aerospace / Safety-Critical | Feature | Description | |---------|-------------| | **Requirement Traceability** | Upload a requirements CSV — Grasp scans for `@REQ-NNN` tags and shows coverage %, missing, and unspecified files. One-click compliance matrix export. | | **MISRA / Safety Mode** | `⋯ → 🔧 Safety Mode` — detect MISRA C/C++ and Ada violations: dynamic allocation after init, recursive calls, `goto`, `abort()`/`exit()`. | | **DO-178C / ECSS Certification Export** | One-click certification evidence package: inventory, traceability matrix, complexity, MISRA violations, security findings — JSON and printable HTML. | | **Anomaly Investigation** | Select file → 🔍 Anomaly Investigation — callers, callees, transitive blast radius, recent commits, security in call path, plain-English summary. | | **Software Reuse Assessor** | Traffic-light matrix across Interface Compatibility, Dependencies, Safety Level, Architecture Fitness, Security, Complexity. | | **Cross-language Call Graph** | Ada→C `pragma Import`, Python `ctypes`/`cffi`, JS→WASM boundaries. | | **Heritage Software Genealogy** | Overlay an origin-mission manifest, identify zero-delta certification shortcuts. | | **ICD Mapper** | Match Interface Control Document entries to exported functions, flag unimplemented interfaces. | | **ECSS-E-ST-40C Compliance** | Check DI-01, DI-04, DI-07, DI-10, DI-15 compliance requirements. | ### 🧠 AI Research | Feature | Description | |---------|-------------| | **Safety Constraint Tracer** | Mark safety gates (filters, sanitizers) — trace every entry→output path and flag any that bypass all gates. New **Safety** color mode. | | **Research/Production Boundary** | Define research vs production folders — flags production files that import from research code. | | **Jupyter Notebook Support** | `.ipynb` in the dependency graph — extracts code cells, parses imports, flags reproducibility issues. | | **Training Run Diff** | Upload two YAML/JSON configs — diff hyperparameters and find which files read each changed key. | | **Eval Coverage Map** | Auto-detects eval scripts and traces which model/training code they exercise. Safety gates with no eval coverage flagged as critical. | | **ML Pipeline DAG** | Detects PyTorch, TensorFlow, JAX, HuggingFace patterns — renders Data→Model→Training→Eval→Checkpoint DAG. | ### 🏢 Enterprise | Feature | Description | |---------|-------------| | **SBOM Generation** | CycloneDX 1.4 or SPDX 2.3 JSON for npm, pip, Cargo, Go modules. Optional CVE enrichment via OSV API. | | **DORA Metrics** | Deployment Frequency, Lead Time, Change Failure Rate, MTTR from GitHub Actions. Elite/High/Medium/Low classification. | | **AI-Powered ADR Generation** | One-click MADR-format Architecture Decision Records using codebase context + optional PR diff. | | **PII Data Flow Tracer** | BFS from user-marked PII source files — shows all downstream consumers. | | **Separation of Duties** | Detects files that both initiate and approve transactions (SOX/FDA compliance). | | **Regulatory Change Impact** | Keywords-to-blast-radius for GDPR/HIPAA/SOX/PCI-DSS article changes. | | **Finance / Trading** | Latency hotspot detection — blocking I/O, GC pressure, lock contention, allocation in loops. | | **Financial Model Risk** | Hardcoded parameters, missing NaN checks, division without zero-guard. | --- ## Token-Reduction Benchmark *(v3.18.0)* `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. ```bash # Build the MCP server first cd mcp && node build.mjs && cd .. # Run the full benchmark (clones 6 repos to /tmp/grasp-eval, ~5 minutes) node scripts/eval-token-reduction.mjs # Or just one repo node scripts/eval-token-reduction.mjs --only got ``` Outputs to `docs/benchmarks/token-reduction.{md,json}`. Verified end-to-end on `got@v14.0.0`: 113,438 → 35 tokens. --- ## For AI Agents — MCP Server Grasp 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. ### Setup ```bash # Install npm install -g grasp-mcp-server # Or run without installing npx grasp-mcp-server ``` Add to `~/.claude/claude_mcp_settings.json`: ```json { "mcpServers": { "grasp": { "command": "npx", "args": ["-y", "grasp-mcp-server"] } } } ``` Works with GitHub repos and local directories. See [`mcp/README.md`](mcp/README.md) for GitLab, Docker, and self-hosted options. ### Claude Code Slash Commands *(v3.18.0)* Three pre-built slash commands ship in `.claude/commands/` so any Claude Code workspace can invoke Grasp's most common flows in one step: | Command | What it does | |---------|-------------| | `/grasp:build-graph` | Runs `grasp_analyze` on the current dir + `grasp_minimal_context` for a sub-100-token orientation | | `/grasp:review-delta` | Detects changes since base branch and produces a risk-scored impact report | | `/grasp:review-pr` | Full PR review composing detect_changes + suggested_questions + surprising_connections + knowledge_gaps | Each command is a markdown file with allowed-tools and template body. Edit them in-repo to customize. ### Tools Reference > **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). **Core Analysis** | Tool | What it does | |------|-------------| | `grasp_analyze` | Full analysis of any repo or local path — returns `session_id` for follow-up queries | | `grasp_sessions` | List active sessions (persist 7 days, survive restarts) | | `grasp_diff` | Compare two snapshots — what changed between analyses? | | `grasp_watch` | Re-analyse a directory and diff against a prior run | | `grasp_rules_check` | Run `grasp.yml` architecture rules and report violations | | `grasp_config_check` | Validate a session against architecture rules — returns violations | **File & Code Intelligence** | Tool | What it does | |------|-------------| | `grasp_file_deps` | What does this file depend on? | | `grasp_dependents` | What breaks if I change this file? | | `grasp_cycles` | Are there circular dependencies? | | `grasp_architecture` | What layers does this codebase have? | | `grasp_hotspots` | Which files are riskiest to touch? | | `grasp_metrics` | Lines, complexity, fan-in/fan-out per file | | `grasp_find_path` | How does file A connect to file B? | | `grasp_patterns` | What design patterns are in use? | | `grasp_unused` | Dead code — defined but never called | | `grasp_explain` | Plain-English explanation of any file or function | | `grasp_refactor` | Step-by-step refactor plan for a file or session | | `grasp_suggest` | Ranked refactoring suggestions by effort-to-impact ratio | | `grasp_onboard` | Ordered reading path for new engineers entering a codebase area | | `grasp_types` | Type annotation coverage — prioritises high fan-in files lacking types | | `grasp_similarity` | Ranked duplicate clusters and code-clone groups | | `grasp_stale` | Active but abandoned files — low churn, high fan-in, no test counterpart | | `grasp_change_risk` | Risk score 0–100 for a set of changed files | **Security & Compliance** | Tool | What it does | |------|-------------| | `grasp_security` | Hardcoded secrets, injection risks, dangerous patterns | | `grasp_sbom` | SBOM in CycloneDX 1.4 or SPDX 2.3 JSON | | `grasp_sarif` | SARIF 2.1.0 export for GitHub Code Scanning | | `grasp_license` | Dependency licenses — flags copyleft and unknown | | `grasp_pii_trace` | BFS trace from PII source files to all consumers | | `grasp_duties` | Separation of duties — files that both initiate and approve | | `grasp_reg_impact` | Regulatory change blast radius (GDPR/HIPAA/SOX/PCI-DSS) | | `grasp_env_vars` | All env var reads — flags undocumented and test-only vars | | `grasp_feature_flags` | All feature flag reads (LaunchDarkly, GrowthBook, env-var flags) | **Team & DevOps** | Tool | What it does | |------|-------------| | `grasp_pr_comment` | Generate PR health comment with blast radius for changed files | | `grasp_pr_review` | Post inline review comments on a GitHub PR at high-severity lines | | `grasp_commits` | Commit counts for last 7d and 30d | | `grasp_ci_status` | Latest GitHub Actions run — passing/failing/in-progress | | `grasp_dora` | DORA metrics — Deployment Frequency, Lead Time, CFR, MTTR | | `grasp_adr` | AI-powered MADR-format Architecture Decision Record | | `grasp_embed` | Generate iframe, README badge, React snippet for sharing | | `grasp_timeline` | Last N commits with per-commit changed files + co-change matrix | | `grasp_contributors` | Per-file ownership, bus-factor, top contributors | | `grasp_coverage` | Test coverage overlay — which files lack tests? | | `grasp_issues` | Map GitHub Issues to the files they mention | | `grasp_jira_issues` | Map Jira issues to source files via project key | | `grasp_service_graph` | Service-level dependency graph from OTEL / custom trace JSON | | `grasp_deps_dev` | Ecosystem dependents via deps.dev — how many packages depend on this repo | **Brain / Intelligence** *(v3.16.0)* | Tool | What it does | |------|-------------| | `grasp_brain_index` | Analyse and persist a repo to the local SQLite brain | | `grasp_brain_status` | What's indexed in the brain and when? | | `grasp_context` | Rich file context — layer, complexity, coupling, security, dependents, dependencies | | `grasp_arch_diff` | Compare current state vs brain baseline — detect degradations | | `grasp_ask` | Ask a natural language question about your architecture | **Graph Core** *(Kuzu — v3.16.0)* | Tool | What it does | |------|-------------| | `graph_query` | Run read-only Cypher queries against the persistent function/file call graph | | `call_chain` | Trace caller and callee chains for any function, up to configurable depth | | `type_propagation` | Find all functions sharing a return type and their call neighbors | | `function_graph` | Render a Mermaid / DOT / JSON subgraph centred on any named function | **Advanced Analysis** | Tool | What it does | |------|-------------| | `grasp_dead_packages` | npm deps in `package.json` but never imported | | `grasp_runtime_calls` | Merge a live runtime trace with static edges — actual hot paths | | `grasp_db_coupling` | ORM/SQL-to-table coupling map — god tables, high-coupling files | | `grasp_migration_plan` | Phased topologically-ordered plan for replacing a package/module | | `grasp_api_surface` | Unified API surface from OpenAPI, GraphQL, Express/FastAPI routes | | `grasp_events` | Event emitters and subscribers — orphaned emits, ghost subscriptions | | `grasp_perf` | N+1 queries, synchronous I/O, JSON serialization in loops | | `grasp_bundle` | Bundle size treemap — largest files by size category | | `grasp_dep_impact` | Impact of upgrading a dependency across all files | | `grasp_cross_repo` | Compare two sessions — shared files, diverged functions | | `grasp_diagram` | Generate Mermaid flowchart or C4 diagrams from the dependency graph | **Aerospace / Safety-Critical Vertical** | Tool | What it does | |------|-------------| | `grasp_req_trace` | Requirement traceability — scan `@REQ-NNN` tags against a CSV | | `grasp_anomaly` | Anomaly investigation — BFS blast radius, security in call chain, plain-English summary | | `grasp_reuse` | Software reuse assessor — Red/Amber/Green compatibility matrix | | `grasp_safety_trace` | Safety constraint tracer — finds paths that bypass all safety gates | | `grasp_multilang` | Cross-language call graph (Ada→C, Python→C, JS→WASM) | | `grasp_heritage` | Heritage software genealogy — zero-delta certification shortcuts | | `grasp_icd` | ICD mapper — match Interface Control Document entries to code | | `grasp_ecss` | ECSS-E-ST-40C compliance checker (DI-01, DI-04, DI-07, DI-10, DI-15) | **AI Research Vertical** | Tool | What it does | |------|-------------| | `grasp_run_diff` | Training run diff — changed hyperparameters and affected code | | `grasp_eval_coverage` | Eval coverage map — safety gates with no eval coverage flagged critical | **Multi-Repo / Platform** | Tool | What it does | |------|-------------| | `grasp_org_graph` | Org-level multi-repo dependency graph with inter-repo edges | | `grasp_api_diff` | Breaking API change detector — removed/changed exported symbols | | `grasp_plugins` | Extension-point map — plugin interfaces, hook points, strategy patterns | | `grasp_semver` | Semantic versioning enforcer — validate semver bump for the change set | | `grasp_abi_diff` | ABI/API stability checker — stability score 0–100 | | `grasp_subsystems` | Kernel/OS subsystem boundary map | | `grasp_kconfig` | Kconfig/build-time conditional analysis — CONFIG_* usage map | | `grasp_irq` | IRQ/interrupt dependency graph — blocking calls, allocation in handlers | | `grasp_patch_impact` | Patch series impact analyzer — rank patches by blast radius + complexity | | `grasp_good_first_issues` | Good first issue generator — isolated, low-complexity, untested files | | `grasp_api_stability` | API stability score (0–100) between two sessions | | `grasp_fork_diff` | Fork divergence analysis — diverged/identical/fork-only files | | `grasp_latency` | Finance/trading latency hotspot detection | | `grasp_model_risk` | Financial model risk auditor | **Code Intelligence *(v3.16.0)*** | Tool | What it does | |------|-------------| | `grasp_diff_symbols` | Map `git diff` hunks to functions — blast radius of a PR before merge | | `grasp_exec_flow` | BFS execution flow from any entry point with STEP_IN_PROCESS edges + Mermaid chart | | `grasp_skillmd` | Auto-generate `SKILL.md` / `CLAUDE.md` snippet from the analysis session | | `grasp_hooks` | Generate `.claude/settings.json` PostToolUse hook + `.cursor/rules/grasp.mdc` | | `grasp_mro` | Method Resolution Order — C3 linearization (Python), MRO for Ruby/Java hierarchies | | `grasp_communities` | Leiden/Louvain community detection — identify bounded contexts and microservice candidates | | `grasp_contracts` | Multi-repo contract analysis — provider exports vs consumer usage, violations + coverage % | **Analysis Intelligence *(v3.16.0)*** | Tool | What it does | |------|-------------| | `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) | | `grasp_wiki` | Auto-generate a markdown wiki: index.md + per-folder pages + api.md sorted by caller count | | `grasp_registry_list` | List all Brain-indexed repos with health grade, file/function counts, and active session IDs | | `grasp_registry_status` | Registry health: indexed count, session count, grade distribution | | `grasp_resolve_receiver` | Resolve the concrete class for every class method — what `self`/`this` refers to across Python, JS, Java, Ruby | **Semantic Search, Rename & Routes *(v3.16.0)*** | Tool | What it does | |------|-------------| | `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 | | `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 | | `grasp_route_map` | Scan for HTTP route definitions (Express/Fastify/Hono, FastAPI/Flask, Gin) — maps each route to its handler function with file location | | `grasp_api_impact` | Given a route or handler name, returns all callers, downstream services, and blast radius using brain graph edges | | `grasp_tool_map` | Scan for MCP tool definitions (`server.tool` / `server.registerTool`) and gRPC service definitions — returns a service contract map | | `grasp_shape_check` | For any function, traces parameter types and return types across all call sites from the brain index; flags call-site mismatches | | `grasp_group_add` | Add a repo source to a named group in `~/.grasp/groups.json` for multi-repo `@groupName` fan-out | | `grasp_group_list` | List all named groups and their member repos from `~/.grasp/groups.json` | **Graph Intelligence *(v3.16.0)*** | Tool | Description | |---|---| | `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 | | `grasp_type_propagation` | Cross-file type inference via Kahn topological sort over import graph; returns top inferred types with confidence 0–1 | | `grasp_orm_map` | ORM query tracker — Prisma, TypeORM, Sequelize, SQLAlchemy; results grouped by model with call sites, operations, frequency | | `grasp_detect_changes` | Git diff → symbol impact: changed files, affected functions, impacted process flows, risk level `LOW`/`MEDIUM`/`HIGH`/`CRITICAL` | | `grasp_generate_agents_md` | Generate rich AGENTS.md from brain session — functional communities, execution processes, health grade, top issues | | `grasp_generate_skills` | Per-community `.claude/skills/generated/<community>.md` files — key files, entry points, cross-area deps | **Graph Analytics & LLM Context** *(v3.18.0)* | Tool | What it does | |------|-------------| | `grasp_hub_nodes` | Top-N most connected files by fan-in + fan-out (degree centrality) | | `grasp_bridge_nodes` | Brandes betweenness centrality. Auto-samples 100 sources for repos > 500 nodes | | `grasp_surprising_connections` | Rare cross-layer edges flagged by frequency-weighted rarity | | `grasp_knowledge_gaps` | Isolated files, untested hotspots, weak communities | | `grasp_suggested_questions` | Auto-generated 5–10 review questions composing all of the above | | `grasp_minimal_context` | Sub-100-token repo orientation — the LLM's first call | | `grasp_traverse` | Token-budget-aware BFS from any starting node | | `grasp_semantic_search` | Cosine similarity over function signatures via @xenova/transformers | | `grasp_apply_refactor` | Executes rename ops with dry_run preview default | | `grasp_architecture_overview` | Combined community + hub + review-question report | | `grasp_export_graphml` | yEd / Gephi-compatible GraphML XML export | | `grasp_export_cypher` | Neo4j CREATE statements that reproduce the graph | | `grasp_export_obsidian` | `.canvas` JSON for Obsidian Canvas with per-layer column layout | | `grasp_export_dot` | Graphviz DOT (`digraph`) — clusters per layer, edge counts, renders on GitHub | | `grasp_export_mermaid` | Mermaid `graph LR` — inline-renders on GitHub, GitLab, Notion, Obsidian | | `grasp_export_d2` | Terrastruct D2 — `direction: right` with layer containers, render via `d2` CLI | | `grasp_export_plantuml` | PlantUML class diagram — works in Confluence, Jira, IntelliJ, VS Code | | `grasp_export_dgml` | Visual Studio Directed Graph XML — opens natively in VS Architecture window | | `grasp_export_gexf` | Gephi-native GEXF 1.3 with layer/lines/complexity/churn node attributes | | `grasp_export_drawio` | draw.io / diagrams.net XML — grid layout, editable in app.diagrams.net | | `grasp_export_csv` | Three-sheet CSV bundle: files, connections, issues — opens in any spreadsheet | **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}` **MCP Prompts *(v3.16.0)*** — `detect_impact` (changes → symbols → processes → risk → test scope) · `generate_map` (repos → analyze → diagram → communities → wiki) --- ## CI/CD Integration ### GitHub Actions — Automatic PR Comments ```yaml # .github/workflows/grasp.yml name: Grasp Health Check on: pull_request: types: [opened, synchronize, reopened] jobs: health: uses: ashfordeOU/grasp/.github/workflows/grasp-health.yml@main ``` The workflow posts and updates a comment on every PR: | Metric | Value | |--------|-------| | **Health Score** | `████████░░` **82/100** | | **Grade** | 🟢 **A** | | **Files** | 142 (891 functions) | | **Architecture Issues** | 3 | | **Circular Deps** | 0 ✓ | | **Security** | 0 ✓ | | **Changed Files** | 5 code files in this PR | ### Architecture Rules (`grasp.yml`) ```yaml rules: - min_health_score: 70 # fail CI if score drops below 70 - max_blast_radius: 20 # flag any file affecting 20+ others ``` Run locally with `grasp . --check`, or use the [GitHub Actions template](docs/examples/grasp-check.yml). ### CLI-based CI Gate ```bash grasp . --report # Writes grasp-report.json, exit 0 = pass, exit 1 = fail ``` ```yaml - name: Grasp health gate run: | PASSED=$(cat grasp-report.json | jq '.ci.passed') SCORE=$(cat grasp-report.json | jq '.ci.score') echo "Health score: $SCORE" if [ "$PASSED" != "true" ]; then cat grasp-report.json | jq '.ci.failures' exit 1 fi ``` See [docs/api-schema.md](docs/api-schema.md) for the full export schema. ### SARIF Upload (GitHub Code Scanning) ```bash grasp . --format=sarif # Writes grasp-results.sarif ``` ```yaml - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: grasp-results.sarif ``` --- ## Advanced Features ### ⚡ Command Palette `Cmd+K` (Mac) / `Ctrl+K` (Windows) — search files, jump to functions, navigate to issues. Selecting a result pans the graph to that node. ### 🔍 Path Finder Select two files in the details panel to find the shortest dependency chain between them. ### 🏛️ Architecture Rule Engine Define custom `FORBIDDEN` dependency rules (e.g., `utils → services` is FORBIDDEN). Violations are flagged as issues and persist across sessions. ### 📅 History & Snapshots Every analysis is saved automatically. Click **HISTORY** in the right panel to compare health scores over time with a D3 sparkline and range slider. ### 🚫 Custom Ignore Patterns `⋯ → 🚫 Ignore Patterns` — add directory exclusions (e.g., `generated/`, `__mocks__/`). Persists across sessions. Built-in defaults (`node_modules`, `dist`, `.git`) cannot be removed. ### 📤 Export Reports JSON, Markdown, Plain Text, SVG, SARIF 2.1.0, plus 11 portable graph formats: GraphML (yEd/Gephi), Cypher (Neo4j), Obsidian Canvas, DOT (Graphviz), Mermaid, D2 (Terrastruct), PlantUML, DGML (Visual Studio), GEXF (Gephi), draw.io, and a three-sheet CSV bundle (files / connections / issues). Every graph format is one click in the in-app Export menu and one MCP tool away (`grasp_export_*`). Full schema in [docs/api-schema.md](docs/api-schema.md). ### ✨ v3.19.0 Team Dashboard Parity Full visual and UX parity between the Team Dashboard and the main Grasp app: - **Teal brand sweep** — all indigo accent tokens replaced with teal `#00d4aa`, matching Grasp's design system exactly. - **Lucide SVG icons** — emoji buttons in the topbar and help modal replaced with proper inline SVG icons throughout. - **Multi-provider auth** — GitLab Token, GitHub Enterprise, Bitbucket, Azure DevOps, and Gitea added to the auth selector, sharing the same localStorage keys as the main app (`grasp_gitlab_token`, `grasp_bb_username`, `grasp_ghe_token`, etc.). - **Mobile More menu** — at ≤860px, secondary topbar buttons collapse into a `···` dropdown. Auth bar flex-wraps on narrow screens. - **Keyboard shortcut popover** — `?` floating button (kbd-fab) shows a hover/click popover with dashboard shortcuts (`/` to focus input, `T` for theme, `Esc` to close, `?` to toggle). ### ✨ v3.18.0 UX Improvements - **Try-it chips** — empty state offers `expressjs/express`, `lodash/lodash`, `sindresorhus/got` quick-start chips for instant demos. - **Token-loaded indicator** — green dot + "Token loaded — 5,000 req/hr" caption when a saved token is detected; otherwise "60 req/hr · Add token →". - **Snapshot URLs** — `📸 Copy snapshot link` bundles the entire analysis into a `#snapshot=<gz-base64>` fragment. Recipient loads instantly, offline, no API calls. - **Compare two repos** — More menu → Compare opens a modal with two URL inputs and renders side-by-side health/files/issues/hubs. - **Mid-analysis rate-limit recovery** — when GitHub returns 403/429 mid-fetch, a recovery card replaces the spinner with a countdown to reset, password input for token, and Resume / Retry / Cancel buttons. - **Mobile touch gestures** — pinch-to-zoom + drag pan on the SVG graph. Right panel auto-collapses below 768px so the graph gets full width. - **Better error messages** — 401 explains how to refresh the token + scope link; 404 includes correction examples; network errors mention Open Folder; every error has a ↻ Retry button. - **Per-repo persistence** — ignore patterns + color mode now save per-repo via `grasp_ignore_patterns_<owner/repo>` and `grasp_color_mode_<owner/repo>`. Restored automatically on next analysis of the same repo. - **Floating ? popover** — bottom-right keyboard-shortcuts hint popover with frosted glass. - **Export menu enhanced** — JSON, Markdown, SBOM (CycloneDX 1.4 / SPDX 2.3), SARIF 2.1.0, GraphML, Copy Snapshot URL. ### 🤖 AI Coding Tool Support Grasp works via MCP with all major AI coding tools: **Claude Code, Cursor, Cline, Roo Code, Kilo Code, OpenCode, Trae, Grok CLI, Codex CLI, Droid** See [`ai-tools/`](./ai-tools/) for per-tool setup guides. ### 🔖 Health Badge ```markdown  ``` ### @grasp-bot in PRs Comment `@grasp-bot analyze` on any PR — Grasp posts a full health report inline. --- ## VS Code Extension > **Install:** Download `grasp-vscode-3.21.0.vsix` from [GitHub Releases](https://github.com/ashfordeOU/grasp/releases/latest), then in VS Code run **Extensions: Install from VSIX…** (`Cmd+Shift+P`). - Auto-analyses workspace on startup, re-analyses on file save (2s debounce) - Status bar shows `↑ N deps ↓ M dependents` for the active file - Pans to the active file on every editor switch - Surfaces security issues and arch violations in the **Problems panel** (squiggly lines) - 4 color mode buttons in the panel header: Layer / Folder / Churn / Complexity - Health score badge in the panel header - Double-click any node to open the file in the editor - Right-click any file → **Grasp: Analyze File** for instant details - Directed links: blue = outgoing imports, green = incoming dependents - Rich tooltips: complexity, churn count, top contributor per file --- ## Keyboard Shortcuts | Key | Action | |-----|--------| | `Enter` | Analyze repository | | `Cmd+K` / `Ctrl+K` | Open command palette | | `+` / `-` | Zoom in/out | | `Shift+click` | Multi-select nodes | | `Escape` | Close modal / command palette | | `T` | Cycle through 19 themes | | `?` | Toggle the keyboard-shortcut popover (bottom-right) | > **In-app help:** every screen in the browser app has a floating `?` button bottom-right that opens a popover listing every shortcut and tab. The Team Dashboard (`team-dashboard.html`) ships its own help modal. If you ever feel lost, press `?`. --- ## Troubleshooting | Problem | Cause | Fix | |---------|-------|-----| | Analysis hangs at "Found N files" | GitHub unauthenticated rate limit (60 req/hr) | Click 🔑 → paste a Personal Access Token (5,000 req/hr). Token stays in `localStorage` only | | `grasp-mcp-server` command not found | Package not in PATH | Use `npx grasp-mcp-server` instead, or `npm install -g grasp-mcp-server` | | Port 7332 already in use | Another Grasp instance running | `lsof -ti:7332 \| xargs kill -9` then re-run | | `grasp_semantic_search` slow on first call | Embedding model is downloading (~30 MB) | First call takes 30-60s; subsequent calls instant. Or set `GRASP_DISABLE_EMBEDDINGS=1` for fallback | | WASM grammar download failed | CDN blocked / offline | Set `GRASP_GRAMMAR_DIR=/path/to/local/grammars` to use local copies | | `Permission denied: ~/.grasp/brain.db` | Multiple users, restrictive umask | `chmod 644 ~/.grasp/brain.db` or set `GRASP_BRAIN_DIR=/tmp/grasp` | | GitHub Actions: "Repository not found" | Token lacks `repo` scope | For private repos, token needs `repo` (not just `public_repo`) | | Browser extension popup blank | MV3 service worker not registered | Reload from `chrome://extensions` → Developer mode → ↺ | | Safari extension hidden | Sideloaded extensions disabled | Safari → Develop → Allow Unsigned Extensions | | Chrome Web Store: "Item not updatable" | Extension is in CWS review | Wait ~24-48h; not an error | | `grasp setup` writes nothing | No editor config detected | Check for `.claude/`, `.cursor/`, `.windsurf/` etc. — at least one must exist | | Mid-analysis 403 spinner | Rate limit hit during file fetch | New: a recovery card now appears with countdown + token input. Paste token → Resume | --- ## Glossary | Term | Plain English | |------|---------------| | **MCP (Model Context Protocol)** | An open protocol for AI assistants to call tools. Grasp's MCP server exposes 150 tools to Claude Code, Cursor, etc. | | **AST (Abstract Syntax Tree)** | A tree representation of source code. Grasp uses tree-sitter to build them in 35 languages. | | **tree-sitter** | A parser library that builds ASTs incrementally and accurately. Grasp ships native bindings for 19 languages | | **fan-in / fan-out** | How many other files import this file (in) vs how many it imports (out). High fan-in = critical hub | | **Brandes betweenness centrality** | Algorithm that finds files sitting on the most "shortest paths" between others — chokepoints | | **Leiden / Louvain** | Algorithms that group densely-connected nodes into communities (microservice-candidate detection) | | **Cypher** | The graph-query language used by Kuzu. Grasp lets you run read-only Cypher queries via `graph_query` | | **Kuzu** | An embedded graph database optimised for analytical queries. Stores Grasp's call graph at `~/.grasp/graph/` | | **BM25** | A keyword-search ranking function (the standard in search engines). Used by `grasp_search` for text matches | | **RRF (Reciprocal Rank Fusion)** | Algorithm to merge keyword and vector search results into a single ranked list | | **Brain store** | Grasp's local SQLite cache at `~/.grasp/brain.db` — files, edges, security, coupling, churn | | **Blast radius** | The set of files affected when one file changes — followed transitively through the import graph | | **Cyclomatic complexity** | A score for how many branches/paths a function has. Higher = harder to test | | **Hybrid search** | BM25 (keywords) + vector (semantic) combined via RRF for the best of both worlds | | **Snapshot** | A frozen architecture state saved to brain.db; used to detect drift over time | | **MCP Resources** | URIs like `grasp://repos` that expose live data to MCP clients without a tool call | | **MCP Prompts** | Pre-built guided workflows that compose multiple tools (e.g., `detect_impact` chains 5 tools) | | **Slash commands** | Pre-built `.claude/commands/*.md` files that give Claude Code shortcut buttons | --- ## 19 Themes Full theme system with hover picker and click-to-cycle: **Dark** · **Light** · **Matrix** · **Amber Terminal** · **Dracula** · **Nord** · **Tokyo Night** · **Catppuccin** · **Gruvbox** · **Obsidian Gold** · **Midnight Diamond** · **Carbon** · **Noir** · **Synthwave** · **Ocean Depth** · **Forest** · **Sunset** · **High Contrast** · **Solarized Light** Theme choice persists across sessions and is shared between Grasp and Team Dashboard. --- ## Supported Languages JavaScript · TypeScript · Python · Go · Java · Rust · C · C++ · C# · Ruby · PHP · Swift · Kotlin · Scala · Vue · Svelte · Dart · Elixir · Erlang · Haskell · Lua · R · Julia · Perl · Shell · PowerShell · F# · OCaml · Clojure · Elm · VBA · Groovy · Ada · Zig --- ## GitHub API Rate Limits | Auth | Requests/hour | |------|--------------| | No token | 60 | | Personal Access Token | 5,000 | | GitHub App | 5,000 per installation | --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Analysis Engine (mcp/src/) │ │ │ │ ┌──────────────────────┐ ┌──────────────────────────────────────┐ │ │ │ AST Parser │ │ Analyzer + Pipeline │ │ │ │ tree-sitter WASM │ │ · Dependency extraction │ │ │ │ 35 languages │ │ · Cyclomatic complexity │ │ │ │ native bindings │ │ · Layer classification │ │ │ └──────────────────────┘ │ · Security pattern detection │ │ │ │ · Dead code & duplicate analysis │ │ │ ┌──────────────────────┐ │ · Scope resolver (3-tier, 0.95→0.50)│ │ │ │ Source Adapters │ │ · Type propagator (Kahn topo-sort) │ │ │ │ GitHub · GitLab │ │ · ORM tracker (Prisma/TypeORM/SA) │ │ │ │ Azure · Bitbucket │ └──────────────────────────────────────┘ │ │ │ Gitea · Local FS │ │ │ └──────────────────────┘ ┌──────────────────────────────────────┐ │ │ │ Brain Store (~/.grasp/brain.db) │ │ │ │ SQLite · repos / files / edges │ │ │ │ FTS5 full-text · 384D vectors │ │ │ │ Execution process tags (BFS) │ │ │ └──────────────────────────────────────┘ │ │ ┌──────────────────────────────────────┐ │ │ │ Graph Store (~/.grasp/graph/) │ │ │ │ Kuzu — Schema v3 │ │ │ │ Nodes: File · Function · Class │ │ │ │ Interface · Method │ │ │ │ Constructor · TestFile │ │ │ │ Edges: CALLS(conf) · IMPORTS │ │ │ │ EXTENDS · IMPLEMENTS │ │ │ │ HAS_METHOD · OVERRIDES │ │ │ │ QUERIES · STEP_IN_PROCESS │ │ │ │ TESTS · COVERS │ │ │ │ Read-only Cypher via graph_query │ │ │ └──────────────────────────────────────┘ │ └────────────────────────────────────┬────────────────────────────────────┘ │ ┌─────────────────────────┼─────────────────────────┐ ▼ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────┐ │ Browser Apps │ │ MCP Server + CLI │ │ IDE Extensions │ │ │ │ (grasp-mcp-server) │ │ │ │ index.html │ │ │ │ VS Code │ │ · React + D3 │ │ 150 tools │ │ JetBrains │ │ · 10 graph views │ │ 8 MCP Resources │ │ Zed │ │ · AI Chat (11 prov) │ │ 2 guided Prompts │ │ Neovim · Vim │ │ · Confidence overlay │ │ Brain (SQLite+Kuzu) │ │ Emacs │ │ · Graph query modal │ │ Hybrid search │ │ Eclipse · Continue │ │ · Fn-level canvas │ │ Graph analytics(v3.18) │ │ │ │ · DB coupling tab │ │ ORM map · Change risk │ │ Browser Extensions │ │ · Compare mode (v3.18) │ │ Route/API map │ │ Chrome · Firefox │ │ · Snapshot URLs (v3.18) │ │ @group fan-out │ │ Safari │ │ · PII detection │ │ Arch diff · Hooks │ │ │ │ · 19 themes │ │ grasp setup │ │ Setup auto-config │ │ · Try-it chips │ │ (Claude/Cursor/ │ │ grasp setup [path] │ │ · Token indicator │ │ Windsurf/Codex/ │ │ writes mcp.json + │ │ │ │ OpenCode) │ │ hooks for all │ │ team-dashboard.html │ │ --watch --timeline │ │ detected editors │ │ · Multi-repo health │ │ --format=sarif │ │ │ │ · DORA + sparklines │ │ --pr-comment │ │ │ │ · Patterns/Env/Flags │ │ --http (HTTP server) │ │ │ │ · Registry panel │ │ │ │ │ │ · WebSocket rooms │ │ │ │ │ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────┘ │ │ │ └─────────────────────────┴─────────────────────────┘ │ ┌────────────────────────────────────▼────────────────────────────────────┐ │ Integrations │ │ │ │ CI/CD Bots & Alerts AI Coding Tools Project Mgmt │ │ GitHub Action Slack Bot Claude Code Jira │ │ GitLab CI Discord Bot Cursor Linear │ │ Bitbucket Pipe Teams Bot Windsurf · Codex Raycast │ │ CircleCI Orb @grasp-bot Copilot Extension │ │ Jenkins Plugin Amazon Q · Cline │ │ GPT Actions · Roo │ │ │ │ Self-hostable SaaS API (saas/) · badge service · GitHub OAuth │ └─────────────────────────────────────────────────────────────────────────┘ ``` **Browser app:** zero dependencies to install. React 18, D3.js 7, Babel from CDNs. Tree-sitter WASM grammars load lazily and cache in IndexedDB. **MCP server:** Node.js 18+. Native tree-sitter bindings for AST-backed function extraction and cyclomatic complexity across 19 languages: Python, Go, Java, Kotlin, Rust, C, C++, C#, Ruby, JavaScript, TypeScript, TSX, Swift, PHP, Scala, Zig, Bash, Elixir, Julia. **Brain store:** two persistent stores — SQLite at `~/.grasp/brain.db` (file metadata, coupling, security) and Kuzu graph DB at `~/.grasp/graph/` (function call graph, imports, return-type edges — queryable via Cypher). **Knowledge graph (MCP server):** three new module groups under `mcp/src/` — `ingest/` (PDF, DOCX, XLSX, HTML, image OCR, audio/video via local Whisper, YouTube, URL; heavy parsers are optional lazy-loaded deps), `llm/` (`provider.ts` — a local-first multi-provider layer that auto-detects Ollama before any cloud key, with a zero-credential deterministic fallback; supports Anthropic/OpenAI/Gemini/DeepSeek/Kimi/Azure/Bedrock/Ollama), and `semantic/` (SQLite `kg.db` of EXTRACTED/INFERRED entities and relations with source locators, hybrid BM25 + vector retrieval, BFS path-tracing, hub/god-node detection). Exposed via `grasp_ingest` / `grasp_kg_*` / `grasp_llm_status`; optionally shared across a team over HTTP (`GRASP_HTTP_MCP=1`, optional `GRASP_HTTP_API_KEY`, port 7333, `/health`). **IDE extensions:** VS Code (`vscode-extension/`), JetBrains (`jetbrains-plugin/`), Zed, Neovim, Vim, Emacs, Eclipse, Continue — all backed by the same MCP server. **Browser extensions:** Chrome, Firefox, and Safari (`browser-extension/`, `safari-extension/`) — MV3, inject a floating Grasp button on GitHub and GitLab pages. --- ## Version & Auto-Update Both `index.html` and `team-dashboard.html` display the current version (`v3.21.0`) in the footer. On load, they silently check the npm registry for a newer release. If found, a dismissible toast appears: - **Update Now** — fetches the new HTML from GitHub, downloads it, and applies it immediately - **Later** — snoozes for 24 hours No server, no background process. --- ## Privacy & Security **Your code stays on your machine.** **Browser app:** - Runs 100% in the browser — no server, no proxy - GitHub/GitLab API calls go directly from your browser to the provider - Your token lives in `localStorage` only — never sent anywhere except the chosen Git provider - No analytics, no tracking, no accounts - The entire app is [one open-source HTML file](index.html) — audit it yourself **MCP server:** - Runs locally as a subprocess — no outbound connections except the GitHub/GitLab API - No telemetry, no data collection - Local directory analysis is read and discarded in memory; Brain store stays on your machine at `~/.grasp/brain.db` **Supply chain:** - Every npm release is signed with [SLSA provenance](https://slsa.dev) (Level 2) via GitHub Actions OIDC - Every Docker image (`ghcr.io/ashfordeou/grasp`) is signed with Cosign keyless signatures, recorded in the [Sigstore Rekor](https://rekor.sigstore.dev) public ledger **Full privacy policy:** [PRIVACY.md](PRIVACY.md) — zero data collection, plain-language statement of what each surface (browser app, MCP server, CI bot, hosted SaaS) does and does not transmit. Verify before installing: ```bash # npm package npm install -g @sigstore/verify # one-time sigstore verify npm grasp-mcp-server@3.21.0 # Docker image cosign verify \ --certificate-identity-regexp="https://github.com/ashfordeOU/grasp/.github/workflows/publish.yml" \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ ghcr.io/ashfordeou/grasp:v3.21.0 ``` --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, code structure, and PR checklist. **Found a bug?** [Open an issue](https://github.com/ashfordeOU/grasp/issues) **Adding a language?** Tree-sitter grammar sources are in `mcp/src/extractors/` — follow the existing pattern for a new language file. **Adding an MCP tool?** Register in `mcp/src/index.ts` following the existing `server.registerTool` pattern. Add tests in `mcp/tests/`. --- ## License **Elastic License 2.0** — Copyright (c) 2026 Ashforde OÜ. Free to use, modify, and self-host. You may not offer Grasp as a hosted or managed service, strip copyright notices, or redistribute it under a different brand. See [LICENSE](LICENSE) for full terms. --- <div align="center"> **150 MCP tools · 35 languages · 11 AI providers + 200+ models · zero install · zero data collection** *Dependency graphs, security scanner, DORA metrics, and Grasp Brain — everywhere you write code.* </div>