> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iriscode.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Drop a .irisconfig.json at your project root to share thresholds across your team. Covers presets, custom thresholds, gate limits, and severity overrides.

Drop a `.irisconfig.json` at your project root and commit it - every developer on the team runs Iris Code with the same thresholds, no per-machine drift. Iris Code resolves the nearest config file by walking up the directory tree, so monorepos can have per-package configs without any extra setup.

<Note>
  **Priority order:** nearest folder `.irisconfig.json` → workspace root `.irisconfig.json` → personal default → VS Code settings → built-in defaults
</Note>

## Config presets (Free + Pro)

The fastest way to get started is a preset. Add `presetId` and commit - your whole team is aligned in one line, no threshold spreadsheet required.

```json .irisconfig.json theme={null}
{
  "presetId": "legacy"
}
```

Available presets: `strict`, `balanced`, `legacy`, `security`, `typescript`.

<Tabs>
  <Tab title="Free">
    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.
  </Tab>

  <Tab title="Pro">
    The preset acts as a base layer. Any threshold you override locally is merged on top, giving your team a customisable baseline without starting from scratch.
  </Tab>
</Tabs>

## 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.

```json .irisconfig.json theme={null}
{
  // 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
  "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](/enforcement/security-smells) 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](/enforcement/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                                           |
| `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](/configuration/scoring-weights) for the full reference and examples.

## 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` |

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