graqle 0.31.5

Give your AI tools architecture-aware reasoning. Build a knowledge graph from any codebase — dependency analysis, impact analysis, governed AI answers with confidence scores. Works with Claude Code, Cursor, VS Code Copilot. 14 LLM backends, fully offline capable.

GraQle

Code intelligence that understands your architecture.

Your AI reads files. GraQle gives it a knowledge graph of your entire codebase — dependencies, impact paths, and institutional memory — so it reasons over structure, not strings.

pip install graqle && graq scan repo . && graq run "what depends on auth?"

Website · Dashboard · PyPI · Changelog

---

Table of Contents

• Why GraQle
• Quick Start
• What You Can Do
• IDE Integration (MCP)
• 14 LLM Backends
• Architecture
• What GraQle Understands
• Installation Options
• CLI Reference
• SCORCH — UX Friction Auditing
• Python SDK
• Cloud Sync
• Pricing
• System Requirements
• Security & Privacy
• Contributing
• FAQ
• License & Innovation

---

Why GraQle

The problem

AI coding tools are fast but structurally blind. They see files, not architecture. They read 60 files to answer a dependency question — burning 50,000 tokens, taking minutes, and still guessing. They forget everything between sessions. They cannot tell you what breaks before you break it.

This is not a model problem. It is a context problem.

The solution

GraQle builds a knowledge graph from your codebase that any AI tool can reason over. Every module becomes a node. Every import, call, and dependency becomes an edge. Instead of reading raw files, your AI queries the graph — getting precise, structured context in 500 tokens instead of 50,000.

The graph tracks dependencies, maps impact paths, remembers lessons, and improves with every query you run.

Before and after

	Without GraQle	With GraQle
"What depends on auth?"	AI reads 60 files, guesses	Graph traversal, exact answer in 5s
Tokens per question	50,000	500
Cost per question	~$0.15	~$0.0003
Impact analysis	Manual grep + hope	graq impact auth.py — full blast radius
Institutional memory	Buried in Slack threads	graq learn — the graph remembers
Cross-session context	Lost when chat resets	Persistent knowledge graph
Confidence in answers	"I think..."	Confidence score + evidence chain

Who uses GraQle

• Individual developers working with AI coding assistants who want better answers, faster
• Engineering teams who need dependency analysis and impact tracking across shared codebases
• Open source maintainers who want contributors to understand architecture without reading every file
• Tech leads and architects who need governed AI reasoning with audit trails

---

Quick Start (60 seconds)

Prerequisites: Python 3.10+

# Install
pip install graqle

# Scan your codebase and build the knowledge graph
graq scan repo .

# Ask anything about your architecture
graq run "what does the auth module depend on?"

Connect to your IDE in one command:

graq init                          # Claude Code — auto-wires MCP tools
graq init --ide cursor             # Cursor — MCP + .cursorrules
graq init --ide vscode             # VS Code + Copilot
graq init --ide windsurf           # Windsurf — MCP + .windsurfrules

Your AI now has architecture-aware tools. No workflow change — it uses them automatically.

---

What You Can Do

Understand your codebase

graq run "explain the payment flow end to end"
graq context auth-module           # 500-token focused context for any module

Ask architectural questions in plain English. GraQle reasons over the dependency graph, not raw files.

Analyze impact before changes

graq impact auth.py
# → Shows: 3 direct consumers, 11 transitive dependencies, risk: HIGH

See every affected module before you touch a line of code. No more "I didn't realize that was connected."

Get safety checks before refactoring

graq preflight "refactor the database layer"
# → Warnings: 4 modules depend on connection pool, 2 have no tests

Governance-aware preflight checks surface risks before you commit, not after you deploy.

Build institutional memory

graq learn "auth module requires refresh token rotation — never skip it"
graq lessons auth
# → Returns lessons learned, ranked by relevance

The graph remembers what your team learns. New developers and AI assistants inherit that knowledge automatically.

Connect your AI tools

graq init                          # MCP server with 16 tools for Claude, Cursor, Copilot

Your AI assistant gets graph-powered reasoning, impact analysis, and safety checks — all through the standard MCP protocol.

Cross-project analysis

graq link merge ../backend ../frontend    # Merge graphs from multiple repos
graq link infer                           # Discover cross-project dependencies
graq link stats                           # See how your projects connect

Monorepo or multi-repo — GraQle maps relationships across boundaries.

Compile intelligence

graq compile
# → Risk scores, impact radii, 135+ actionable insights, CLAUDE.md auto-injection

One command produces a full intelligence report: risk heatmaps, module rankings, and auto-generated context files your AI tools consume directly.

Audit UX friction automatically

pip install "graqle[scorch]" && python -m playwright install chromium
graq scorch run --url http://localhost:3000
# → 5-phase audit: screenshots, CSS metrics, 12 behavioral tests, Claude Vision, journey score
# → Findings auto-added to your knowledge graph

SCORCH v3 — GraQle's first-party UX audit plugin. 12 behavioral friction tests, 6 archetype classifications, and Claude Vision journey psychology. Runs from CLI, MCP, or Python. Full details below.

---

IDE Integration (MCP)

GraQle implements the Model Context Protocol so any MCP-compatible IDE can query your knowledge graph directly.

Setup

Claude Code — add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "graqle": {
      "command": "graq",
      "args": ["mcp", "serve"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "graqle": {
      "command": "graq",
      "args": ["mcp", "serve"]
    }
  }
}

VS Code + Copilot — add to .vscode/mcp.json:

{
  "servers": {
    "graqle": {
      "command": "graq",
      "args": ["mcp", "serve"]
    }
  }
}

If graq is not on your PATH (common on Windows / WSL / virtualenv), use the universal Python fallback:

{
  "mcpServers": {
    "graqle": {
      "command": "python",
      "args": ["-m", "graqle.cli.main", "mcp", "serve"]
    }
  }
}

Or skip manual config entirely: graq init auto-detects your IDE and wires everything.

Available MCP Tools

Tool	Description	Tier
graq_context	Focused context for a module (~500 tokens)	Free
graq_inspect	Graph structure: nodes, edges, stats	Free
graq_reason	Multi-agent graph reasoning	Free
graq_reason_batch	Batch reasoning over multiple queries	Free
graq_preflight	Governance check before code changes	Pro
graq_lessons	Query relevant lessons and past mistakes	Pro
graq_impact	Trace downstream impact through the dependency graph	Pro
graq_safety_check	Pre-change safety analysis with risk scoring	Pro
graq_learn	Record outcomes for graph learning	Pro
graq_reload	Hot-reload the knowledge graph	Free
graq_audit	Retrieve audit trail for any reasoning session	Pro
graq_gate	Governance gate check (pass/fail)	Pro
graq_drace	Quality scoring across 5 governance dimensions	Pro
graq_runtime	Runtime configuration and diagnostics	Free
graq_route	Task routing information across backends	Free
graq_lifecycle	Module lifecycle and deprecation tracking	Pro
graq_scorch_audit	Full SCORCH v3 UX audit (5-phase pipeline)	Pro
graq_scorch_behavioral	12 behavioral UX friction tests (no AI cost)	Free
graq_scorch_report	Read and summarize a SCORCH audit report	Free

---

14 LLM Backends

One config line switches your reasoning backend. Use your own API keys or run fully offline.

# graqle.yaml
model:
  backend: anthropic    # or: openai, groq, ollama, bedrock, gemini, deepseek, ...

Backend	Best For	Pricing
Ollama / llama.cpp	Offline, air-gapped, privacy	$0 (local)
Groq	Speed — sub-second responses	~$0.0005/query
DeepSeek	Budget-conscious teams	~$0.0001/query
Anthropic	Complex reasoning (Claude)	~$0.001/query
OpenAI	GPT-4o, broad compatibility	~$0.001/query
Google Gemini	Long context windows	~$0.0001/query
AWS Bedrock	Enterprise, IAM integration (uses standard boto3 credential chain: env vars, ~/.aws/credentials, SSO, instance profiles)	AWS pricing
Together	Open-source model hosting	~$0.0003/query
Mistral	European data residency	~$0.0003/query
Fireworks	Fast open-source inference	~$0.0003/query
Cohere	Enterprise RAG workflows	~$0.0005/query
OpenRouter	Model marketplace, any model	Varies
vLLM	Self-hosted GPU inference	$0 (self-hosted)
Custom	Any OpenAI-compatible endpoint	Your pricing

Smart routing — assign different providers to different task types:

routing:
  default_provider: groq              # Fast + cheap for lookups
  rules:
    - task: reason
      provider: anthropic             # Claude for deep reasoning
    - task: context
      provider: groq                  # Groq for instant context retrieval

Config field reference: The routing section uses default_provider and default_model (not fallback_*). Run graq config to see your fully resolved configuration, or graq config --json for CI pipelines.

---

Architecture

Your Code                    Knowledge Graph               AI Reasoning
┌─────────────┐             ┌──────────────────┐          ┌─────────────────┐
│ Python      │  graq scan  │  Nodes (modules) │  query   │ Graph-of-Agents │
│ TypeScript  │ ──────────> │  Edges (depends) │ ───────> │ Multi-round     │
│ Config      │             │  Skills (201)    │          │ Confidence-scored│
│ Docs        │             │  Lessons         │          │ Audit-trailed   │
└─────────────┘             └──────────────────┘          └─────────────────┘
                                    │
                              graq learn
                                    │
                            Graph evolves with
                            every interaction

Every file becomes a node. Every import, call, and dependency becomes an edge. When you ask a question, only the relevant nodes activate, reason about their domain, and synthesize one precise answer — with a confidence score and full evidence chain.

The graph is not static. graq learn feeds outcomes back into edge weights. The more you use GraQle, the better it understands your codebase.

---

What GraQle Understands

Languages

Language	Support
Python	Full — imports, classes, functions, decorators, type hints
JavaScript / TypeScript	Full — imports, exports, JSX, async patterns
React / JSX / TSX	Full — components, hooks, props, context
Go	Structural — packages, imports, function signatures
Rust	Structural — modules, use declarations, traits
Java	Structural — packages, imports, class hierarchy

Frameworks

FastAPI, Django, Flask, Next.js, React, Express, NestJS — GraQle recognizes framework-specific patterns like route decorators, middleware chains, and dependency injection.

Relationships Tracked

Imports, function calls, class inheritance, API endpoint definitions, environment variable usage, configuration references, package dependencies, cross-file type references.

Documents

PDF, DOCX, PPTX, XLSX, Markdown — graq scan docs ./docs ingests documentation into the graph alongside code, linking architecture decisions to the modules they describe.

---

Installation Options

pip install graqle                    # Core SDK + CLI (zero cloud dependencies)
pip install "graqle[api]"             # + Anthropic, OpenAI, Bedrock providers
pip install "graqle[docs]"            # + PDF, DOCX, PPTX, XLSX parsing
pip install "graqle[neo4j]"           # + Neo4j graph backend (for large codebases)
pip install "graqle[embeddings]"      # + Sentence transformers for semantic search
pip install "graqle[scorch]"          # + SCORCH v3: AI-powered UX friction auditing
pip install "graqle[all]"             # Everything

For development:

git clone https://github.com/quantamixsol/graqle && cd graqle
pip install -e ".[dev,api]"
pytest                                # 1,700+ tests

Upgrading:

graq self-update                      # Recommended — handles MCP server locks on Windows
pip install --upgrade graqle          # Alternative — may require stopping MCP server first
graq migrate                          # After upgrade: rename legacy cognigraph files to graqle

Auto-scales: starts with JSON + NetworkX (zero infrastructure), recommends Neo4j at 5,000+ nodes.

---

CLI Reference

Scan & Build

Command	Description
graq init	Scan repo, build graph, auto-wire IDE integration
graq scan repo .	Scan codebase into knowledge graph
graq scan docs ./docs	Ingest documents into the graph
graq scan file path.py	Scan a single file
graq compile	Compile intelligence: risk scores, insights, CLAUDE.md
graq verify	Run governance gate checks

Query & Reason

Command	Description
graq run "question"	Natural language query (auto-routed)
graq reason "question"	Multi-agent graph reasoning
graq context module-name	Focused 500-token context
graq impact module-name	Downstream impact analysis
graq preflight "planned change"	Pre-change safety check
graq lessons topic	Surface relevant lessons

Teach & Learn

Command	Description
graq learn node "name" --type SERVICE	Add a node to the graph
graq learn edge "A" "B" -r DEPENDS_ON	Add a relationship
graq learn doc architecture.pdf	Ingest a document
graq learn discover .	Auto-discover entities from code
graq learned	List what the graph has learned

Cross-Project

Command	Description
graq link merge ../other-repo	Merge graphs from multiple repos
graq link infer	Discover cross-project dependencies
graq link stats	Cross-project relationship statistics

Cloud & Infrastructure

Command	Description
graq login --api-key grq_...	Authenticate with graqle.com
graq cloud push	Upload graph to cloud
graq cloud pull	Download graph to local
graq cloud status	List cloud projects
graq studio	Open visual dashboard
graq serve	Start REST API server
graq mcp serve	Start MCP server for IDE integration
graq doctor	Health check and diagnostics (includes reasoning smoke test)
graq config	Show resolved configuration (backend, model, routing, graph)
graq config --json	Machine-readable config output for CI/scripting
graq self-update	Upgrade to latest version (handles MCP server locks on Windows)
graq migrate	Migrate legacy cognigraph files to graqle branding

SCORCH — UX Friction Auditing

Command	Description
graq scorch run	Full 5-phase audit (screenshots + CSS + behavioral + Vision + report)
graq scorch behavioral	12 behavioral UX tests only (fast, no AI cost)
graq scorch a11y	WCAG 2.1 AA/AAA accessibility audit
graq scorch perf	Core Web Vitals (LCP, CLS, FID) + resource analysis
graq scorch seo	Meta tags, Open Graph, structured data, heading hierarchy
graq scorch mobile	Touch targets, viewport, text readability, pinch-zoom
graq scorch i18n	Internationalization: lang, RTL, date/currency formatting
graq scorch security	CSP headers, exposed API keys, XSS vectors, mixed content
graq scorch conversion	CTA placement, form quality, trust signals, pricing clarity
graq scorch brand	Color palette, typography, logo, spacing consistency
graq scorch auth-flow	Login/signup/dashboard flows with auth state comparison
graq scorch diff	Before/after report comparison with improvement metrics
graq scorch config --init	Create default SCORCH config file
graq scorch report	View the latest audit report

---

SCORCH — UX Friction Auditing

New in v0.30 — SCORCH v3 is GraQle's first-party plugin for AI-powered UX friction auditing. It finds the invisible UX issues that make users quit — not just visual bugs, but broken user journeys.

pip install "graqle[scorch]" && python -m playwright install chromium
graq scorch run --url http://localhost:3000 --page / --page /pricing

5-Phase Pipeline

Phase	What It Does	Cost
1. Screenshots	Full-page captures at mobile, tablet, desktop	Free
2. CSS Metrics	Font sizes, touch targets, overflow, contrast	Free
2.5. Behavioral UX	12 automated friction pattern tests	Free
3. Claude Vision	AI analysis + Journey Psychology scoring	~$0.05/page
4. Report	Combined JSON + Markdown report with pass/fail	Free

12 Behavioral Friction Tests

Every test maps to real user frustration — not theoretical heuristics:

Test	What It Catches
Dead Clicks	Buttons/links that look clickable but do nothing
Silent Submissions	Forms that submit without any visible feedback
Unexplained Jargon	Acronyms without tooltips or definitions
Ghost Elements	Empty containers with borders but no content
Missing Next-Step CTA	Pages that end without telling the user what to do next
Copy-Paste Friction	Content in non-selectable elements
Missing Inline Editor	AI-generated text with no edit/copy affordance
Incomplete Generation	Truncated AI output with no "show more"
Feature Discoverability	Interactive elements hidden behind display:none
Flow Continuity	Dead-end pages with no back link or navigation
Upsell Integrity	Upgrade prompts shown for already-owned tiers
Action-Response Feedback	Buttons without loading states or confirmation

6 Friction Archetypes

SCORCH classifies every issue into one of six universal UX failure patterns:

1. No Visible Response — "Is it working?" — User acts but nothing changes
2. Response Mismatch — "Not what I asked for" — UI promises X, delivers Y
3. Unusable Output — "Now what do I do with this?" — Results the user can't act on
4. User Stranded — "Okay... now what?" — Process completes but no next step
5. User Confused — "I'm lost" — User doesn't understand the UI
6. UI Contradicts State — "That's wrong" — UI shows incorrect information

MCP Integration

SCORCH exposes 13 tools via the GraQle MCP server — your AI assistant can audit UX directly:

MCP Tool	Description	Cost
graq_scorch_audit	Full 5-phase audit with pass/fail, journey score, issue list	~$0.05/page
graq_scorch_behavioral	12 behavioral UX friction pattern tests	Free
graq_scorch_report	Read and summarize an existing audit report	Free
graq_scorch_a11y	WCAG 2.1 AA/AAA accessibility audit (contrast, aria, focus, headings)	Free
graq_scorch_perf	Core Web Vitals: LCP, CLS, FID, resource analysis, render-blocking	Free
graq_scorch_seo	SEO: meta tags, Open Graph, Twitter Cards, JSON-LD, canonical	Free
graq_scorch_mobile	Mobile: touch targets (44px min), viewport, readability, scroll	Free
graq_scorch_i18n	i18n: html lang, RTL, hardcoded strings, date/currency formatting	Free
graq_scorch_security	Security: CSP, exposed API keys, XSS, mixed content, HSTS	Free
graq_scorch_conversion	Conversion: CTA inventory, form quality, trust signals, pricing	Free
graq_scorch_brand	Brand: color palette, typography, spacing, button consistency	Free
graq_scorch_auth_flow	Auth flows: login/signup/dashboard with auth state comparison	Free
graq_scorch_diff	Before/after comparison: resolved/new issues, improvement %	Free

All tools are also available with the kogni_scorch_* prefix for backward compatibility.

Auto KG Enrichment

Critical and major findings are automatically added to your GraQle knowledge graph as FRICTION_FINDING nodes. This means your AI assistant knows about UX issues when reasoning about your codebase — connecting code changes to UX impact.

Behavioral-Only Mode (Free, No AI)

Don't want to use Claude Vision? Run just the 12 behavioral tests — zero AI cost, instant results:

graq scorch behavioral --url http://localhost:3000 --page / --page /dashboard

---

Python SDK

from graqle.core.graph import Graqle
from graqle.backends.api import AnthropicBackend

graph = Graqle.from_json("graqle.json")
graph.set_default_backend(AnthropicBackend(model="claude-sonnet-4-6"))

result = graph.reason("What services depend on auth?", max_rounds=3)
print(result.answer)                  # Graph-reasoned answer
print(f"{result.confidence:.0%}")     # Confidence score
print(f"${result.cost_usd:.4f}")      # Token cost

Full programmatic access to scanning, reasoning, impact analysis, and graph manipulation.

---

Cloud Sync

New in v0.29 — sync knowledge graphs across machines and team members.

graq login --api-key grq_your_key       # Get key at graqle.com/dashboard/account
graq cloud push                         # Graph appears on graqle.com/dashboard
graq cloud pull                         # Download on any machine
graq cloud status                       # See all your projects

Push from your laptop, pull on your workstation. Share with your team. View and explore on graqle.com/dashboard.

Cloud sync uploads the graph structure only — never your source code.

---

Pricing

The SDK is 100% open source and always free. Cloud features are optional.

	Free ($0)	Pro ($19/mo)	Team ($29/dev/mo)
CLI + SDK + MCP server	Unlimited	Unlimited	Unlimited
All 14 LLM backends	Yes	Yes	Yes
Intelligence + governance	Yes	Yes	Yes
SCORCH behavioral tests	Yes	Yes	Yes
SCORCH Vision + Journey	--	Yes	Yes
Graph nodes	500	25,000	Unlimited
Cloud projects	1	3	Unlimited
Reasoning sessions	3/month	100/month	Unlimited
Cross-project analysis	--	Yes	Yes
Team shared graphs	--	--	Yes
Priority support	--	Yes	Yes

Start free at graqle.com

---

System Requirements

Requirement	Minimum	Recommended
Python	3.10+	3.12+
RAM	2 GB	4 GB (large codebases)
Disk	~100 MB (SDK + deps)	~500 MB (with embeddings)
OS	Windows, macOS, Linux	Any

No Docker, no database, no cloud account required for local use. Neo4j is optional for codebases above 5,000 nodes.

---

Security & Privacy

• Local by default. All scanning, graph building, and reasoning runs on your machine.
• No telemetry. GraQle does not phone home or collect usage data.
• Your API keys. LLM calls go directly from your machine to your chosen provider.
• Cloud is opt-in. graq cloud push uploads graph structure only — never source code.
• Auditable. Source code is fully readable. See SECURITY.md for our security model.

---

Patent Notice

GraQle implements methods covered by European Patent Applications EP26162901.8 and EP26166054.2, owned by Quantamix Solutions B.V.

Use of graqle is permitted under the license terms. Reimplementation of the patented methods outside this software requires a separate patent license. See LICENSE for details.

---

Contributing

git clone https://github.com/quantamixsol/graqle && cd graqle
pip install -e ".[dev]" && pytest     # 1,700+ tests

We welcome contributions: bug fixes, new backend integrations, language scanner improvements, and documentation. See CONTRIBUTING.md for guidelines.

---

FAQ

Why not just use Cursor / Claude Code / Copilot directly? GraQle does not replace your AI tool — it makes it dramatically better. Your AI reads files one at a time and guesses at relationships. With GraQle, it queries a knowledge graph that maps your entire architecture. Same AI, 100x fewer tokens, answers grounded in actual dependency structure. Plugs in via MCP with zero workflow change.

Does my code leave my machine? Never. All processing is local. LLM calls go directly to your chosen provider using your API keys. Cloud sync is opt-in and only uploads graph structure — never source code.

How is this different from Sourcegraph or static analysis? Static analysis tells you what code exists. GraQle tells you how it connects, what breaks when it changes, and what your team has learned about it. It is a reasoning layer, not a search engine. Every answer comes with a confidence score and evidence chain.

What about large monorepos? GraQle starts with JSON + NetworkX (zero infrastructure). At 5,000+ nodes, switch to Neo4j with one config line. Cross-project linking (graq link merge) works across repos. The graph scales — the interface stays the same.

Can I use my own LLM? Yes. 14 backends out of the box — including Ollama and llama.cpp for fully offline, air-gapped operation. Any OpenAI-compatible endpoint works via the Custom backend. Use your own API keys, your own models, your own infrastructure.

How long does the initial scan take? Under 30 seconds for most codebases. Large monorepos (10,000+ files) take 1-2 minutes. Incremental scans after the first are near-instant.

Does GraQle work without an LLM? Yes. Scanning, graph building, impact analysis, and the visual dashboard all work without any LLM. You only need a backend configured for graq reason and graq run queries.

Is this production-ready? 1,700+ tests. 396 compiled modules. 14 backends. Used in production by the team that builds it. That said, the version is 0.x — the API is stable but we reserve the right to make breaking changes with major version bumps.

---

License & Innovation

GraQle is free to use, integrate, and deploy. See LICENSE for full terms.

The SDK implements methods covered by European Patent Applications EP26162901.8 (18 claims) and EP26166054.2 (15 claims), owned by Quantamix Solutions B.V. Use of the SDK is licensed — reimplementation of the patented methods outside this software requires a separate patent license.

Built by Quantamix Solutions B.V. — Uithoorn, The Netherlands.

Citation

@article{kumar2026graqle,
  title   = {GraQle: Governed Intelligence through Graph-of-Agents Reasoning
             over Knowledge Graph Topologies with Semantic SHACL Validation},
  author  = {Kumar, Harish},
  year    = {2026},
  institution = {Quantamix Solutions B.V.},
  note    = {European Patent Applications EP26162901.8 and EP26166054.2},
  url     = {https://github.com/quantamixsol/graqle}
}

---

Your AI is only as good as the context you give it. Give it your architecture.

pip install graqle && graq init

graqle.com