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:

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

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/mcp-server  — MCP server (21 tools, 9 resources, 6 prompts, sampling, roles)
├── @nomik/github-bot  — PR impact analysis webhook
├── @nomik/viz         — React + 3D force-graph + Cytoscape.js dashboard
└── @nomik-ai/cli      — 38 CLI commands

Tech Stack

Development

git clone https://github.com/willFreed1/NOMIK.git
cd NOMIK && pnpm install && docker compose up -d && pnpm build
pnpm test                     # 232 tests
pnpm nomik scan . --project nomik
pnpm nomik doctor             # Verify setup

Documentation

Contributors

Nomik is an evolving tool built to supercharge AI coding. We welcome all contributions!

Whether it's fixing bugs, adding support for new languages, creating new graph insights, or improving documentation—feel free to open an issue or submit a Pull Request.

License & Contributions

Nomik is licensed under the Functional Source License (FSL) v1.1.

• Can I use Nomik for free? Yes, for personal projects, academic research, or internal company tools.
• Can I contribute? Yes! We welcome pull requests and community contributions.
• What can't I do? You cannot use the Software to provide a product or service that competes with Nomik itself (e.g., offering "Nomik as a Service").
• What happens later? After 2 years, the code automatically transitions to the Apache 2.0 license.

For the full legal terms, see the LICENSE file.