Configuration

Complete configuration reference — environment variables, architecture rules, custom Cypher rules, and multi-project management.

Environment Variables

nomik init automatically generates a .env file at your project root with all Nomik variables. You can also create it manually — all variables are optional and have sensible defaults.

.env

NOMIK_GRAPH_URI=bolt://localhost:7687
NOMIK_GRAPH_USER=neo4j
NOMIK_GRAPH_PASS=nomik_local
NOMIK_GRAPH_DRIVER=neo4j
NOMIK_PROJECT_ID=my-project
NOMIK_LOG_LEVEL=info
NOMIK_MCP_PORT=3334
NOMIK_VIZ_PORT=3333
NOMIK_ROLE=dev
NOMIK_SAMPLING=false

Make sure .env is in your .gitignore — it contains your Neo4j credentials.

Full Reference

Variable	Default	Description
`NOMIK_GRAPH_URI`	`bolt://localhost:7687`	Neo4j Bolt connection URI
`NOMIK_GRAPH_USER`	`neo4j`	Neo4j username
`NOMIK_GRAPH_PASS`	`nomik_local`	Neo4j password
`NOMIK_GRAPH_DRIVER`	`neo4j`	Graph driver type (`neo4j` or `memgraph`)
`NOMIK_PROJECT_ID`	(all projects)	Default project scope for MCP tools and CLI
`NOMIK_ROLE`	`dev`	MCP role filter (`dev`, `architect`, `security`, `pm`)
`NOMIK_SAMPLING`	`false`	Enable MCP sampling (server→client LLM completions)
`NOMIK_LOG_LEVEL`	`info`	Pino log level (`debug`, `info`, `warn`, `error`)
`NOMIK_MCP_PORT`	`3334`	MCP server port (SSE transport)
`NOMIK_VIZ_PORT`	`3333`	Visualization dashboard port

Architecture Rules

Nomik includes a declarative rules engine with 9 built-in rules. Generate the config file:

nomik rules --init

This creates .nomik/rules.yaml:

.nomik/rules.yaml

maxDeadCode: 5
maxGodFiles: 3
maxGodFileThreshold: 15
maxDuplicates: 2
maxFunctionCallers: 50
maxDbWritesPerRoute: 3
noCircularImports: true
maxFunctionLines: 200
maxFileLines: 1000
maxSecurityIssues: 0

Built-in Rules

Rule	Default	Severity	What It Checks
`maxDeadCode`	5	error	Functions never called and not exported from barrel files
`maxGodFiles`	3	error	Files containing more than 15 functions (configurable via `maxGodFileThreshold`)
`maxDuplicates`	2	warning	Groups of functions with identical bodyHash (≥3 lines)
`maxFunctionCallers`	50	warning	Functions with excessive callers (high fan-in)
`maxDbWritesPerRoute`	3	warning	Routes that trigger too many DB write operations
`noCircularImports`	true	error	Circular import chains between modules
`maxFunctionLines`	200	warning	Functions exceeding line count threshold
`maxFileLines`	1000	warning	Files exceeding line count threshold
`maxSecurityIssues`	0	error	Hardcoded secrets or security findings

Custom Cypher Rules

Add custom rules that run arbitrary Cypher queries against the graph. Each rule specifies a query and fails if the result count exceeds maxResults.

.nomik/rules.yaml

customRules:
  - name: no-direct-db-in-controllers
    description: Controllers should not directly access the database
    severity: error
    maxResults: 0
    cypher: |
      MATCH (f:Function)-[:WRITES_TO|READS_FROM]->(t:DBTable)
      WHERE f.filePath CONTAINS 'controller'
        AND f.projectId = $projectId
      RETURN f.name as name, f.filePath as filePath

  - name: no-external-calls-in-models
    description: Model layer should not call external APIs
    severity: warning
    maxResults: 0
    cypher: |
      MATCH (f:Function)-[:CALLS_EXTERNAL]->(api:ExternalAPI)
      WHERE f.filePath CONTAINS 'model'
        AND f.projectId = $projectId
      RETURN f.name as name, api.name as api

Running Rules

nomik rules              # Evaluate all rules, print results
nomik rules --json       # JSON output for CI

Project Management

Nomik supports multiple projects in a single Neo4j database. Every node and edge carries a projectId property for logical isolation.

nomik project list           # List all projects
nomik project create my-api  # Create a new project
nomik project switch my-api  # Switch active project
nomik project info           # Current project statistics
nomik project delete my-api  # Delete project and all its data

The active project is stored in .nomik/project.json. CLI commands and MCP tools automatically filter by the active project. You can override with --project <name> on any CLI command or the project parameter on any MCP tool.

Runtime Requirements

Component	Required Version
Node.js	≥ 20 LTS
Neo4j	≥ 5.x (Community or Enterprise)
Docker	For Neo4j (optional if using external instance)
pnpm	≥ 9 (for monorepo development only)

On this page