Getting Started
Install Nomik, scan your codebase, and connect your AI editor in under 5 minutes.
Prerequisites
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | ≥ 20 LTS | Runtime for CLI and MCP server |
| Docker | Latest | Runs Neo4j container (or use an external Neo4j 5.x instance) |
Quick Start
npm install -g @nomik-ai/cli # 1. Install
nomik init # 2. Start Neo4j + create project
nomik scan . # 3. Build the knowledge graph
nomik setup-cursor # 4. Connect your AI editorThat's it. Restart your IDE — your AI assistant now has graph-powered intelligence.
Step-by-Step
1. Install the CLI
$ npm install -g @nomik-ai/cli
added 1 package in 3s
$ nomik --version
1.0.02. Initialize the Project
Navigate to your project directory and run:
$ cd ~/my-api
$ nomik init
✓ Neo4j container started (neo4j:5-community)
✓ Neo4j is ready at bolt://localhost:7687
✓ Created .nomik/project.json (project: my-api)
✓ Schema initialized (17 node types, 19 edge types)
Ready! Run 'nomik scan .' to build your knowledge graph.This creates:
- A
.nomik/project.jsonfile with your project config - A
.envfile with all Nomik environment variables (Neo4j credentials, project ID, etc.) - A Neo4j container running on port 7687 (web browser at 7474)
- The full graph schema with constraints and indexes
The generated .env file contains all Nomik config variables with sensible defaults. Edit it to customize your Neo4j credentials, log level, MCP port, etc. Make sure .env is in your .gitignore.
3. Verify Neo4j
Open http://localhost:7474 in your browser to access the Neo4j web interface.
| Field | Value |
|---|---|
| Connection URL | bolt://localhost:7687 |
| Username | neo4j |
| Password | nomik_local |
If you have an existing Neo4j instance, skip nomik init and configure your connection in a .env file:
NOMIK_GRAPH_URI=bolt://your-host:7687
NOMIK_GRAPH_USER=neo4j
NOMIK_GRAPH_PASS=your-password4. Scan Your Codebase
$ nomik scan .
Scanning: /Users/dev/my-api
Parsing... 312 files (TypeScript: 278, Python: 25, SQL: 9)
Extracting... functions, classes, routes, DB ops, events, metrics
Ingesting... 2847 nodes, 6204 edges
✓ Scan complete in 4.2s
Files: 312
Functions: 2,847
Classes: 89
Routes: 15
DB Tables: 3
Env Vars: 12
Git SHA: a1b2c3dYou can also scan a specific subdirectory with a project name:
$ nomik scan ./src --project my-apiOr use incremental scanning to only re-parse changed files:
$ nomik scan:incremental .
Last scan: a1b2c3d (5 minutes ago)
Current: e4f5g6h
Changed files: 3
M src/services/payment.ts
M src/api/checkout.ts
A src/services/refund.ts
✓ Incremental scan complete in 0.8s (3 files, 47 nodes, 112 edges)5. Connect Your AI Editor
$ nomik setup-cursor
✓ Created .cursor/mcp.json
Server: @nomik-ai/cli (stdio)
Neo4j: bolt://localhost:7687
Project: my-api
Role: dev (full access)
Restart Cursor to activate.Other editors:
nomik setup-windsurf # Creates ~/.codeium/windsurf/mcp_config.json
nomik setup-claude # Creates Claude Desktop config
nomik setup-antigravity # Creates Antigravity Editor configIn stdio mode (default), the IDE launches the MCP server on demand. You do not need to run nomik serve.
6. Verify Everything Works
$ nomik doctor
✓ Node.js: v22.4.0 (>= 20 required)
✓ pnpm: 9.1.0
✓ Neo4j: Connected (5.18.0 Community)
Nodes: 2,847 Edges: 6,204
✓ Project: my-api (.nomik/project.json)
✓ MCP Server: dist/mcp-server.js (found)
✓ Git: a1b2c3d (clean)
✓ Cursor: .cursor/mcp.json (configured)
✓ Docker: docker compose up (neo4j running)Then verify from your AI editor by asking:
"What MCP tools do you have access to?"
You should see 21 Nomik tools listed (e.g., nm_search, nm_impact, nm_health).
7. Try It Out
Here are some things you can ask your AI assistant right away:
"Give me a codebase briefing"
→ AI calls nm_onboard → returns full stats, language distribution, high-risk functions
"What breaks if I change processPayment?"
→ AI calls nm_impact → returns all affected routes, functions, DB tables
"Which functions write to the users table?"
→ AI calls nm_db_impact → returns all READS_FROM and WRITES_TO with file paths
"Are there any dead code or duplicate functions?"
→ AI calls nm_health → returns dead code list, god files, duplicatesCommon Workflows
Live Development
Keep the graph in sync as you edit code:
$ nomik watch .
Watching: /Users/dev/my-api (500ms debounce)
[14:32:15] Changed: src/services/payment.ts
✓ Re-indexed in 0.3s (12 nodes, 28 edges)
⚠️ HIGH IMPACT: processPayment has 23 callers across 8 filesArchitecture Review
$ nomik onboard # One-command codebase briefing
$ nomik rules # Evaluate 9 architecture rules + custom Cypher rules
$ nomik communities # Detect functional clusters
$ nomik flows # Trace execution flows from entry pointsPR Review
$ nomik pr-impact # Blast radius for current branch vs main
$ nomik pr-impact --json # Machine-readable output for CICI/CD Pipeline
$ nomik ci # Full pipeline: scan → rules → guard → audit
$ nomik ci --skip-scan # Skip scan if graph is already up to dateDocumentation
$ nomik wiki --out docs/ # Generate markdown docs from graph
$ nomik changelog --since 7d # Auto-generate changelog
$ nomik badge # Generate health badges for READMEVisualization
$ nomik serve # MCP server + 2D/3D graph dashboard at localhost:3333
$ nomik dashboard # REST API on port 4242 (14 endpoints)Project Management
Nomik supports multiple projects in a single Neo4j database:
$ nomik project list
* my-api (active) 312 files, 2847 nodes
frontend (inactive) 156 files, 1204 nodes
$ nomik project create mobile-app
✓ Created project: mobile-app
$ nomik project switch mobile-app
✓ Switched to project: mobile-appReal-World Scenarios
Scenario 1: "I just joined the team — what does this codebase do?"
Instead of spending days reading code, ask your AI assistant:
"Give me a codebase briefing"The AI calls nm_onboard and returns a complete architecture overview: how many files, functions, routes, DB tables, external APIs, env vars, and which functions are the riskiest (most callers). This turns a multi-day onboarding into a 30-second read.
Scenario 2: "Is it safe to refactor this function?"
Before touching processPayment, ask:
"What breaks if I change processPayment?"The AI calls nm_impact and returns every route, function, cron job, and DB table that depends on it — with file paths and line numbers. No more "I didn't know that cron job existed" surprises after deploying.
Scenario 3: "We have a security audit — are there hardcoded secrets?"
$ nomik guard --ci
$ nomik auditGuard checks for hardcoded secrets (AWS keys, GitHub tokens, Stripe keys, JWT secrets, private keys). Audit cross-references npm vulnerabilities with your dependency graph to show blast radius — which files actually import the vulnerable package.
Scenario 4: "Which tests do I need to re-run?"
After changing a function, instead of running the entire test suite:
$ nomik test-impact processPayment
Test files affected by changes to processPayment:
src/__tests__/payment.test.ts (direct import)
src/__tests__/checkout.test.ts (calls processPayment via route)Scenario 5: "Our CI keeps failing on god files"
$ nomik rules
✓ max-dead-code: 0/5
✗ max-god-files: 4/3 (>15 functions)
- src/controllers/listing.controller.ts (18 functions)
- src/services/user.service.ts (16 functions)Nomik tells you exactly which files need splitting. You can also adjust thresholds in .nomik/rules.yaml or via --god-file-threshold.