grasp

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.

+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

Who is Grasp for?

What makes Grasp different

Grasp is intentionally additive to whatever static-analysis or graph tool you already use. The axes that matter:

Screenshots

🕸️ Dependency Graph — see exactly how files connect

🏛️ Architecture Diagram — your codebase by layer

📦 Treemap — files sized by line count

🏢 Team Dashboard — health across all your repos at a glance

Quick Start

Option 1 — Browser (zero setup)

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

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

Option 4 — Browser Extension

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:

AI-tool integrations *(Grasp called by your assistant via MCP or extension)*

🧭 Safari Sideload Instructions

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.

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

Color Modes

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 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. 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 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 ` 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`).

👥 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 ``, 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.

grasp snapshot ./my-project --name before-refactor
# ... make changes ...
grasp drift ./my-project          # exits 1 if drift is CRITICAL (CI-friendly)

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.

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.

🏢 Org-Level Dashboard *(v3.17.0)*

Analyse an entire GitHub organisation in one command:

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.

🤖 PR Impact GitHub Action *(v3.17.0)*

Add automated architectural impact analysis to every pull request:

# .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.

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

grasp index            # Analyse and persist a repo to the brain
grasp context     # Get rich context for any file
grasp setup [path]           # Install hooks in Claude Code / Cursor / Windsurf
grasp diff             # Compare current analysis vs brain baseline
grasp daemon           # Watch directory and auto-reindex on changes
grasp drift [path]           # Snapshot + diff vs last snapshot; exits 1 on CRITICAL (CI-friendly)
grasp 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.

Registry — All Indexed Repos

`grasp_registry_list` and `grasp_registry_status` expose the full Brain index:

# 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:

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

🧠 AI Research

🏢 Enterprise

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.

# 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

# Install
npm install -g grasp-mcp-server

# Or run without installing
npx grasp-mcp-server

Add to `~/.claude/claude_mcp_settings.json`:

{
  "mcpServers": {
    "grasp": {
      "command": "npx",
      "args": ["-y", "grasp-mcp-server"]
    }
  }
}

Works with GitHub repos and local directories. See `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:

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

File & Code Intelligence

Security & Compliance

Team & DevOps

Brain / Intelligence *(v3.16.0)*

Graph Core *(Kuzu — v3.16.0)*

Advanced Analysis

Aerospace / Safety-Critical Vertical

AI Research Vertical

Multi-Repo / Platform

**Code Intelligence *(v3.16.0)***

**Analysis Intelligence *(v3.16.0)***

**Semantic Search, Rename & Routes *(v3.16.0)***

**Graph Intelligence *(v3.16.0)***

Graph Analytics & LLM Context *(v3.18.0)*

**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

# .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:

Architecture Rules (`grasp.yml`)

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.

CLI-based CI Gate

grasp . --report   # Writes grasp-report.json, exit 0 = pass, exit 1 = fail

- 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 for the full export schema.

SARIF Upload (GitHub Code Scanning)

grasp . --format=sarif   # Writes grasp-results.sarif

- 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.

✨ 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=` 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_` and `grasp_color_mode_`. 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/` for per-tool setup guides.

🔖 Health Badge

![Grasp Health](https://grasp.ashforde.org/badge/owner/repo.svg)

@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, 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

> 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

Glossary

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

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 — 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 (Level 2) via GitHub Actions OIDC
• Every Docker image (`ghcr.io/ashfordeou/grasp`) is signed with Cosign keyless signatures, recorded in the Sigstore Rekor public ledger

Full privacy policy: 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:

# 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 for setup, code structure, and PR checklist.

Found a bug? Open an issue

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 for full terms.