Configure Iris Code with .irisconfig.json - Presets and Rules

A standard nobody agreed on isn’t a standard. Drop a .irisconfig.json at your project root, commit it, and everyone runs the same thresholds, in every editor, on every machine, plus CI. Iris Code looks for the nearest one by walking up from the file it’s analysing, so a monorepo can give each package its own rules without you configuring anything extra.

Priority order: nearest folder .irisconfig.json → workspace root .irisconfig.json → personal default → VS Code settings → built-in defaults

It explains itself

.irisconfig.json is JSONC, so // comments are legal, and every config Iris Code writes is commented. The file should be readable without this page open alongside it. Generated configs also open with a $schema line:

{
  "$schema": "https://www.iriscode.co/schema/v1/irisconfig.schema.json"
}

Your editor handles that on its own, so you get autocomplete on every field and a squiggle when a value is wrong, in VS Code, JetBrains, Neovim or anything else that speaks JSON Schema. No plugin needed. Keep the line if you edit the file by hand. Hover any setting and it tells you what it does. That text comes from the schema bundled with your installed version, not fetched from us, so it works offline, works behind a proxy, and always describes the version you’re actually running rather than whatever we shipped last week.

JetBrains IDEs: if .irisconfig.json reports “JSON standard does not allow comments”, your IDE is holding a user-level override that cancels the file-type registration Iris Code ships. Reinstalling the plugin will not clear it. See the fix in the installation guide.

Config presets (Free + Pro)

Rather than choosing every threshold individually, start from a preset. Add presetId, commit it, and the team is aligned in one line.

.irisconfig.json

{
  "presetId": "legacy"
}

Available presets: strict, balanced, legacy, security, typescript, ai-assisted. The ai-assisted preset uses stricter explicit limits for teams reviewing AI-assisted code at volume. It caps duplicate blocks and suppressions, but does not impose a naming convention.

Free
Pro

Iris Code applies the shipped preset values as the source of truth. Local edits to threshold fields are ignored and receive a yellow warning squiggle in the editor. The preset registry in the extension is the authority, not the file on disk.

Full custom config (Pro)

For complete control over every rule, write out the full config. Every key is optional - include only the ones you want to override.

.irisconfig.json

{
  // Thresholds — structural size limits
  "functionLengthThreshold": 40,
  "fileLengthThreshold": 300,
  "maxFunctionsPerFile": 10,
  "maxImportsPerFile": 8,
  "maxParameterCount": 5,
  "complexityThreshold": 7,

  // Detection toggles — turn individual rule categories on or off
  "enableConsoleLogWarnings": true,
  "enableMagicNumberDetection": true,
  "enableTodoDetection": true,
  "enableLongParamDetection": true,
  "enableUnusedDetection": true,
  "enableMissingReturnTypeWarnings": true,
  "enableSecretsDetection": true,
  "enableSecuritySmells": true,
  "enableDuplicateDetection": true,
  "duplicateBlockMinTokens": 40,

  // Display — UI and sidebar options
  "enableCodeLens": true,
  "enableStatusBar": true,
  "enableInlineDiagnostics": true,
  "inlineDiagnostics": {
    "hardcodedSecrets": true,
    "errorWarnings": false,
    "warningLevelWarnings": false,
    "tsIgnore": true,
    "unusedFunctions": true,
    "anyUsage": true,
    "consoleLogs": false,
    "magicNumbers": false,
    "longParamLists": false,
    "unusedVars": false,
    "todos": false
  },
  "sidebarFontSize": 14,

  // Gate thresholds — used by the CLI and git pre-push hook
  "minHealthScore": 70,
  "gateMaxSecrets": 0,         // Pro — max hardcoded secrets workspace-wide
  "gateMaxComplexity": 12,     // Pro — max complexity score per file
  "gateMaxFileLength": 500,    // Pro — max line count per file
  "gateMaxSmellsPerFile": 8,   // Pro — max total smells in a single file
  "gateMaxSecuritySmells": 0,  // Pro — max security smells workspace-wide
  "gateMaxSuppressions": 5,    // Pro — max iris-ignore suppressions per file
  "gateMaxDuplicateBlocks": 0, // Pro — max duplicate code blocks across the scan
  "gateMaxNamingViolations": 0,// Pro — max naming violations across the scan
  "ignoreSuppressions": false, // Pro — treat all iris-ignore directives as inert

  // Ignore rules — skip files or functions from analysis
  "ignoreFiles": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/generated/**"
  ],
  "ignoreFunctions": [
    "main",
    "handler"
  ],
  "testConvention": "colocated",

  // Severity overrides — change the severity level per rule
  "severityOverrides": {
    "file-too-long": "warning",
    "function-too-long": "warning",
    "too-many-functions": "warning",
    "too-many-imports": "warning",
    "no-exports": "warning"
  },

  // Scoring weights (Pro) — points deducted per finding type
  "healthScoreWeights": {
    "hardcodedSecret": 10,
    "errorWarning": 5,
    "warningWarning": 3,
    "anyUsage": 2,
    "tsIgnore": 3,
    "consoleLog": 1,
    "deepNesting": 2,
    "longParamList": 1,
    "unusedVar": 1,
    "unusedFunction": 2
  }
}

Thresholds

These keys set the structural size limits that trigger warnings in the editor and sidebar.

Key	Default	What it controls
`functionLengthThreshold`	`40`	Lines before a function is flagged
`fileLengthThreshold`	`300`	Lines before a file is flagged
`maxFunctionsPerFile`	`10`	Max functions before the file is flagged
`maxImportsPerFile`	`8`	Max third-party imports before flagging
`maxParameterCount`	`5`	Max parameters before a function is flagged
`complexityThreshold`	`7`	Complexity score that triggers a status bar warning

Detection toggles

Turn individual detection categories on or off without removing findings from the sidebar entirely.

Key	Default	What it controls
`enableConsoleLogWarnings`	`true`	Flag `console.log` / `print()` / `fmt.Print*`
`enableMagicNumberDetection`	`true`	Flag raw numeric literals without a named binding
`enableTodoDetection`	`true`	Flag `TODO` / `FIXME` / `HACK` comments
`enableLongParamDetection`	`true`	Flag functions with too many parameters
`enableUnusedDetection`	`true`	Flag unused variables and functions
`enableMissingReturnTypeWarnings`	`true`	Flag exported functions missing return types (TS/JS only)
`enableSecretsDetection`	`true`	Enable two-layer hardcoded credential scanning (JS/TS, Go, Python)
`enableSecuritySmells`	`true`	Enable the nine security smell patterns (eval usage, SQL concatenation, insecure RNG, and the rest)
`enableDuplicateDetection`	`true`	Detect duplicated code blocks within and across files via normalised token-window matching
`duplicateBlockMinTokens`	`40`	Minimum normalised-token run length before two stretches of code count as a duplicate block (min `10`)

Display

Control what Iris Code renders in the editor UI.

Key	Default	What it controls
`enableCodeLens`	`true`	Show inline Code Lens hints
`enableStatusBar`	`true`	Show the Iris Code item in the status bar
`enableInlineDiagnostics`	`false`	Master toggle for squiggles and Problems panel entries
`sidebarFontSize`	`14`	Base font size in pixels (10–20) for the Iris Code sidebar and detached panel

The inlineDiagnostics object lets you opt individual categories in or out once enableInlineDiagnostics is true.

Gate thresholds

Gate thresholds are enforced by the CLI and git pre-push hook. Files or workspaces that exceed a gate limit fail the check.

Key	Tier	What it controls
`minHealthScore`	Free + Pro	Files below this score are considered failures
`gateBaselineMode`	Pro	Gates existing files against their locked baseline score instead of `minHealthScore` - new files still use `minHealthScore`. Useful for stopping regressions in legacy codebases without requiring a full cleanup.
`trendRegressionThreshold`	Pro	Highlights drops in the Trends table when a file falls by more than this many health-score points between snapshots. Smaller drops can still show as declining; this key controls what Iris Code calls out as a notable regression.
`gateMaxSecrets`	Pro	Max hardcoded secrets allowed workspace-wide - set to `0` to require a clean workspace
`gateMaxComplexity`	Pro	Max complexity score per file; exceeding it fails the gate regardless of health score
`gateMaxFileLength`	Pro	Max line count per file; works alongside `fileLengthThreshold` (which controls warnings)
`gateMaxSmellsPerFile`	Pro	Max total smells in a single file (console logs, magic numbers, long param lists, unused vars/functions, TODOs)
`gateMaxSecuritySmells`	Pro	Max security smells allowed workspace-wide (eval usage, SQL injection risk, insecure RNG, disabled TLS, weak hashing, and the rest of the nine patterns) - set to `0` to require a clean workspace
`gateMaxSuppressions`	Pro	Max inline suppressions (`iris-ignore` directives) allowed in a single file - caps how much a file can silence before the gate fails. Defaults to `5` on the `strict` preset and `3` on `security`; unset elsewhere
`gateMaxDuplicateBlocks`	Pro	Max duplicate code blocks across the whole scan (a block spanning two files counts once) - set to `0` to require a duplication-free codebase. Only counts blocks when `enableDuplicateDetection` is on
`gateMaxNamingViolations`	Pro	Maximum file naming violations across the scan.
`ignoreSuppressions`	Pro	Set to `true` to make every `iris-ignore` directive inert - suppressed findings count as live again. A team-lead kill-switch for audits or when suppressions are being overused

Ignore rules

Key	What it controls
`ignoreFiles`	Glob patterns for files to skip entirely in workspace analysis
`ignoreFunctions`	Function names Iris Code should never flag, regardless of length or complexity
`testConvention`	Where Iris Code looks for test files: `"colocated"` (default), `"dedicated"`, or `"both"`

Scoring weights

healthScoreWeights is a Pro key that lets you override how many points each finding type subtracts from the base 100 health score. See Scoring Weights for the full reference and examples.

Per-language config

Mixed-language repos rarely want one threshold set for everything - a 500-line Python module and a 300-line TypeScript cap should be able to coexist. The languages block overrides per-file settings for typescript, javascript, go, python, ruby, csharp, java, and rust files independently; anything not stated falls back to the base config. .tsx files count as TypeScript and .jsx / .mjs / .cjs as JavaScript. A ruby block also governs the extensionless Ruby files Iris Code reads, such as Gemfile and Rakefile; a csharp block governs both .cs sources and .csproj project files; and a java block governs both .java sources and the .properties files Iris Code reads for credentials.

{
  "fileNaming": {
    "convention": "kebab-case",
    "ignore": [],
    "overrides": [
      { "files": ["**/components/**"], "convention": "PascalCase" },
      { "files": ["**/hooks/**", "**/composables/**"], "convention": "camelCase" }
    ]
  },
  "fileNamingScope": "new-files",
  "fileLengthThreshold": 300,
  "languages": {
    "python": {
      "fileLengthThreshold": 500,
      "fileNaming": { "convention": "snake_case", "scope": "all", "ignore": [] }
    },
    "typescript": {
      "functionLengthThreshold": 35,
      "fileNaming": { "convention": "kebab-case", "ignore": ["src/legacy/**"] }
    },
    "go": { "functionLengthThreshold": 60, "gateMaxSmellsPerFile": 3 }
  }
}

Top-level fileNaming, its ordered overrides, and languages.*.fileNaming are Free. Path overrides are checked in order and the last match wins. When no path rule matches, a nested language policy is a backward-compatible fallback; otherwise the top-level convention applies. Top-level ignore globs remain active throughout. The six length/complexity thresholds, healthScoreWeights, severityOverrides, and per-file gate caps remain Pro. On Free, Iris applies the naming policy and places a warning squiggle on each Pro-only sibling field it ignores. It does not discard the whole language block. Set top-level fileNamingScope to "new-files" (default) or "all". A matching path rule can override it with scope; a language fallback can do the same when no path rule matches. See File naming conventions for the complete precedence contract, baseline behavior, suggestions, ignore globs, and exemptions. Scan-total gates (minHealthScore, gateMaxSecrets, gateMaxSecuritySmells, gateMaxDuplicateBlocks, gateMaxNamingViolations), presetId, and enable* toggles are rejected inside a language block with a validation warning. Resolution happens once, inside the analysis core, so the sidebar, CLI, git hook, build hook, and CI always agree on which threshold applied. The sidebar file tab shows the applied override next to the config source (for example “Workspace config · Python override”), and iris gate prints the limit that actually governed each failing file plus a “Per-language overrides active” note. Unknown language keys (say, an elixir block written for a newer Iris Code) produce a warning and are skipped, so a forward-looking config never breaks an older install. A per-file gate cap set only inside a language block still gates files of that language, even with no top-level cap configured.

Severity overrides

Override the severity of any warning type on a per-project basis using the severityOverrides object. Each key accepts "error", "warning", or "info".

Warning key	Valid severities
`file-too-long`	`error` · `warning` · `info`
`function-too-long`	`error` · `warning` · `info`
`too-many-functions`	`error` · `warning` · `info`
`too-many-imports`	`error` · `warning` · `info`
`no-exports`	`error` · `warning` · `info`

Only include keys you want to override - anything omitted falls back to the preset (if set), then VS Code settings, then built-in defaults.

Start here

What Iris Code finds

Blocking bad code

Configuration

Editors

Reference

Configure Iris Code with .irisconfig.json - Presets and Rules

It explains itself

Config presets (Free + Pro)

Full custom config (Pro)

Thresholds

Detection toggles

Display

Gate thresholds

Ignore rules

Scoring weights

Per-language config

Severity overrides

​It explains itself

​Config presets (Free + Pro)

​Full custom config (Pro)

​Thresholds

​Detection toggles

​Display

​Gate thresholds

​Ignore rules

​Scoring weights

​Per-language config

​Severity overrides

It explains itself

Config presets (Free + Pro)

Full custom config (Pro)

Thresholds

Detection toggles

Display

Gate thresholds

Ignore rules

Scoring weights

Per-language config

Severity overrides