Grasp — Codebase Analysis & Architecture Intelligence README

English · हिन्दी · 日本語 · 한국어 · 简体中文

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

               

🌐 Browser App  ·  📦 MCP Server  ·  🐛 Report Bug  ·  ✨ Request Feature  ·  🔒 Privacy

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:

Channel	Status	Link
npm (grasp-mcp-server)		npm install -g grasp-mcp-server
MCP Registry	Listed	modelcontextprotocol.io
Docker (ghcr.io/ashfordeou/grasp)		docker pull ghcr.io/ashfordeou/grasp:latest
VS Code	.vsix on Releases	GitHub Releases
JetBrains	Marketplace	Plugin ID 31362
Raycast	Store (PR per release)	raycast.com/ashfordeOU/grasp
Zed	Extension (PR per release)	zed.dev/extensions
Chrome	Web Store	CWS listing
Firefox	AMO (listed)	addons.mozilla.org
Safari	Sideload (macOS 13+)	GitHub Releases
GitLab bot image	ghcr.io/ashfordeou/grasp-gitlab-bot	Auto-pushed per release
GitLab tunnel agent	Binary on Releases	GitHub Releases
GitHub Release	Signed + checksums	Releases page

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

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

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

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

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

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