NOMIK — The Living Blueprint

⭐⭐ If you find NOMIK useful, please consider giving it a star on GitHub! It helps the project grow! ⭐⭐ Follow the creator on X: @willfreed01 | Website: hamzabenjeddi.com

AI-native code intelligence graph. Scan once, query everything.

NOMIK builds a persistent Knowledge Graph of your entire codebase in Neo4j, then exposes it to AI assistants via MCP (Model Context Protocol). Instead of dumping files into a prompt, the AI queries a graph to retrieve exactly the relationships it needs — functions, classes, imports, call chains, DB operations, infrastructure, and more.

Quick Start

# Prerequisites: Node.js 20+, Docker
npm install -g @nomik-ai/cli

cd your-project/
nomik init                          # Config + Neo4j Docker + .env + project setup
nomik scan .                        # Build the knowledge graph
nomik setup-cursor                  # Connect to your IDE (or: setup-windsurf, setup-claude)
nomik watch .                       # (Optional) Live graph updates on save

Restart your IDE — the AI now has full graph-powered context.

MCP Tools (21)

Your AI assistant gets these tools automatically:

| Tool | Purpose | Example | |---|---|---| | nm_search | Find symbols by name | "Find all auth functions" | | nm_context | Full context for a symbol | "Show everything about GraphService" | | nm_impact | Downstream impact analysis | "What breaks if I change parseFile?" | | nm_db_impact | DB table/column read/write analysis | "Who writes to users.email?" | | nm_explain | Symbol deep-dive (callers, callees, edges) | "Explain createGraphService" | | nm_health | Stats + health checks (17 node types) | "Any dead code or god files?" | | nm_path | Shortest path between two symbols | "How does scanCommand reach neo4j?" | | nm_trace | Full dependency chain | "Trace from A to B" | | nm_changes | Recently modified nodes | "What changed today?" | | nm_onboard | Full codebase briefing | "Give me a project overview" | | nm_wiki | Generate structured docs | "Generate docs for this codebase" | | nm_communities | Functional cluster detection | "What are the main code modules?" | | nm_flows | Execution flow tracing | "Show the auth request lifecycle" | | nm_guard | Quality gate (dead code, god files, dupes) | "Does the codebase pass quality?" | | nm_rename | Graph-aware rename impact | "What changes if I rename createWatcher?" | | nm_diff | Architecture drift between scans | "What changed between these commits?" | | nm_service_links | Cross-service dependencies | "How do microservices communicate?" | | nm_test_impact | Affected tests after a change | "Which tests for parseFile?" | | nm_audit | Dependency vulnerability + blast radius | "Any vulnerable packages?" | | nm_rules | Architecture rules (9 built-in + custom Cypher) | "Does code follow our policies?" | | nm_projects | List tracked projects | "What projects exist?" |

What NOMIK Tracks

All extractors are import-aware — they resolve receiver variables from actual imports, not hardcoded names.

Code

• Functions, Classes, Imports/Exports — full AST extraction (TS, JS, Python, Rust)
• Call chains — intra-file, cross-file, obj.method(), callbacks, barrel re-exports
• Routes — Express, Fastify, NestJS, tRPC, gRPC, GraphQL (decorator + chain detection)
• Dead code, god files, duplicates — health detection with configurable thresholds

Data

• Database — Prisma, Supabase, Knex, TypeORM, raw SQL, EF/Django/Alembic migrations
• Redis — ioredis, @redis/client, @upstash/redis (read/write/delete classification)
• Job Queues — Bull/BullMQ, Bee-Queue, Agenda, pg-boss (producer/consumer edges)

Infrastructure

• HTTP Clients — axios, got, node-fetch, ofetch, undici, superagent, fetch()
• Message Brokers — KafkaJS, amqplib, NATS, AWS SQS/SNS, Google PubSub
• Tracing — OpenTelemetry, Datadog, Sentry (span creation tracking)
• Metrics — prom-client, OpenTelemetry (Counter/Gauge/Histogram/Summary)
• WebSockets — ws, @nestjs/websockets, uWebSockets.js, Socket.io (rooms/namespaces)
• Cron Jobs — node-cron, node-schedule, @nestjs/schedule, Agenda
• Feature Flags — LaunchDarkly, Unleash, Flagsmith, Split.io, GrowthBook

Config & Security

• Docker/K8s — Dockerfile, docker-compose, K8s manifests (Deployment, Service, Ingress)
• CI/CD — GitHub Actions, GitLab CI (jobs, steps, triggers)
• IaC — Terraform (.tf), CloudFormation/SAM, OpenAPI specs
• Secrets — AWS keys, GitHub tokens, Stripe keys, JWT, private keys, basic auth URLs
• Env vars — .env files, process.env.*, Python os.environ
• Swagger/OpenAPI — decorator enrichment + spec file parsing
• GraphQL schemas — .graphql/.gql file parsing
• Dependencies — package.json, requirements.txt
• Tests — .test./.spec./__tests__/ detection, mock target resolution

Python-Specific

• Redis, Celery tasks, Prometheus metrics, OpenTelemetry spans, Kafka/RabbitMQ/NATS

MCP Extras

Prompts (6 conversation starters)

nomik-onboard, nomik-review-change, nomik-health-check, nomik-explain-module, nomik-migration-plan, nomik-infrastructure

Resources (9 browsable endpoints)

nomik://stats, nomik://health, nomik://files, nomik://communities, nomik://onboard, nomik://schema, nomik://projects, nomik://infrastructure, nomik://guard

Role-Scoped Access

Set NOMIK_ROLE env var: dev (all tools), architect, security, pm — filters tools/prompts/resources per role.

MCP Sampling

Set NOMIK_SAMPLING=true — enables server→client LLM completion requests for AI-augmented analysis.

CLI Commands (38)

# Core
nomik init                    # Setup + Neo4j Docker + project
nomik scan <path>             # Build knowledge graph
nomik scan:incremental <path> # Re-parse only changed files (git diff)
nomik watch [path]            # Live file watcher
nomik status                  # Graph stats
nomik doctor                  # Diagnose setup (Neo4j, MCP, config)

# Analysis
nomik impact <symbol>         # Downstream impact analysis
nomik explain <symbol>        # Full symbol context report
nomik test-impact <symbol>    # Which tests to re-run after a change
nomik migrate <symbol>        # Guided migration plan with risk level
nomik rename <old> <new>      # Graph-aware rename (--apply to write)
nomik diff <sha1> <sha2>      # Architecture drift between scans
nomik service-links           # Cross-service producer/consumer pairs
nomik communities             # Functional cluster detection
nomik flows                   # Execution flow tracing from entry points

# Quality & CI
nomik rules                   # Architecture rules engine (9 built-in + custom Cypher)
nomik rules --init            # Create .nomik/rules.yaml config
nomik guard                   # Quality gate (CI/pre-commit)
nomik audit                   # Dependency vulnerability check + blast radius
nomik ci                      # Unified pipeline: scan → rules → guard → audit

# Documentation & Reporting
nomik onboard                 # One-command codebase briefing
nomik wiki                    # Generate markdown docs from graph
nomik changelog               # Auto-generate changelog from graph changes
nomik badge                   # Shields.io health badges
nomik query "<cypher>"        # Raw Cypher query
nomik recent                  # Recently changed nodes

# IDE Setup
nomik setup-cursor            # Auto-configure Cursor MCP
nomik setup-windsurf          # Auto-configure Windsurf MCP
nomik setup-antigravity       # Auto-configure Antigravity MCP
nomik setup-claude            # Auto-configure Claude Desktop MCP

# Server
nomik dashboard               # REST API on port 4242 (14 endpoints)
nomik serve                   # MCP server + viz dashboard

# Project Management
nomik project list|create|switch|delete|info

Supported Languages

| Language | Parser | Extractors | |---|---|---| | TypeScript / JavaScript | tree-sitter | Full: functions, classes, imports, routes, calls, APIs, DB, Redis, queues, metrics, events, env vars, secrets, tests | | Python | tree-sitter | functions, classes, imports, calls + Redis, Celery, Prometheus, OTel, Kafka/RabbitMQ | | Rust | tree-sitter | functions, structs/enums/traits, use, calls | | Markdown | regex | sections (h1-h6) | | SQL / C# / Python migrations | regex | DB schema extraction (CREATE TABLE, EF, Django, Alembic) | | YAML | regex | Docker Compose, K8s, GitHub Actions, GitLab CI, CloudFormation, Prometheus, OpenAPI | | Terraform | regex | Resources, variables, modules, outputs (.tf, .tfvars) | | GraphQL | regex | Types, queries, mutations, subscriptions (.graphql, .gql) | | Dockerfile | regex | Base images, exposed ports, stages | | .env | regex | Environment variable definitions (.env, .env.local, .env.production) | | JSON configs | regex | package.json dependencies, OpenAPI specs, Grafana dashboards |

Graph Schema

17 Node Types: File, Function, Class, Variable, Module, Route, ExternalAPI, DBTable, DBColumn, CronJob, Event, EnvVar, QueueJob, Metric, Span, Topic, SecurityIssue

23 Edge Types: CONTAINS, IMPORTS, EXPORTS, EXTENDS, IMPLEMENTS, CALLS, DEPENDS_ON, HANDLES, READS_FROM, WRITES_TO, CALLS_EXTERNAL, TRIGGERS, EMITS, LISTENS_TO, USES_ENV, PRODUCES_JOB, CONSUMES_JOB, USES_METRIC, STARTS_SPAN, PRODUCES_MESSAGE, CONSUMES_MESSAGE, HAS_SECURITY_ISSUE, SCHEDULES

Architecture

nomik/
├── @nomik/core        — Types (Zod), config, logger (Pino)
├── @nomik/parser      — Tree-sitter AST extraction + 37 extractors + config file parser
├── @nomik/graph       — Neo4j driver, queries, cache, rules engine
├── @nomik/watcher     — Chokidar file watcher
├── @nomik/mc