⭐⭐ 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.
# 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 saveRestart your IDE — the AI now has full graph-powered context.
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?" |
All extractors are import-aware — they resolve receiver variables from actual imports, not hardcoded names.
- 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
- 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)
- 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
- 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 —
.envfiles,process.env.*, Pythonos.environ - Swagger/OpenAPI — decorator enrichment + spec file parsing
- GraphQL schemas —
.graphql/.gqlfile parsing - Dependencies — package.json, requirements.txt
- Tests —
.test./.spec./__tests__/detection, mock target resolution
- Redis, Celery tasks, Prometheus metrics, OpenTelemetry spans, Kafka/RabbitMQ/NATS
nomik-onboard, nomik-review-change, nomik-health-check, nomik-explain-module, nomik-migration-plan, nomik-infrastructure
nomik://stats, nomik://health, nomik://files, nomik://communities, nomik://onboard, nomik://schema, nomik://projects, nomik://infrastructure, nomik://guard
Set NOMIK_ROLE env var: dev (all tools), architect, security, pm — filters tools/prompts/resources per role.
Set NOMIK_SAMPLING=true — enables server→client LLM completion requests for AI-augmented analysis.
# 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| 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 |
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
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
| Component | Technology |
|---|---|
| Language | TypeScript (ESM, strict) |
| Graph DB | Neo4j 5 Community |
| Parser | Tree-sitter (multi-lang) |
| AI Protocol | MCP (Model Context Protocol) SDK 1.26.0 |
| IDE Support | Cursor, Windsurf, Antigravity, Claude Desktop |
| Monorepo | Turborepo + pnpm workspaces |
| Visualization | Three.js (3D) + Cytoscape.js (2D) |
| Tests | Vitest — 232+ tests, 18+ files |
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| Doc | Description |
|---|---|
| Vision & Roadmap | Why NOMIK exists, full-stack intelligence roadmap |
| Architecture | System diagram, monorepo structure, data flow |
| Running Guide | Step-by-step local setup |
| MCP Integration | IDE connection guide |
| Graph Schema | All node/edge types with Cypher examples |
| Progress Tracker | Version history and changelog |
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.
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.