---
url: /guide/configuration.md
description: >-
  Configure claudelint with rules, presets, ignore patterns, overrides, and
  output options using .claudelintrc.json or package.json.
---

# Configuration

claudelint supports configuration through multiple methods, allowing you to customize linting rules and behavior for your project.

## Configuration Files

claudelint will automatically search for configuration files in the following order:

1. `.claudelintrc.json` - JSON configuration file (recommended)
2. `package.json` - Configuration in the `claudelint` field

The search starts in the current directory and walks up the directory tree until a configuration file is found or the root is reached.

## Configuration Format

### Basic Structure

```json
{
  "extends": "string or array",
  "rules": {
    "rule-name": "severity"
  },
  "overrides": [],
  "ignorePatterns": [],
  "output": {},
  "reportUnusedDisableDirectives": false
}
```

### Extends

The `extends` field allows you to inherit configuration from other config files or npm packages.

**Relative paths:**

```json
{
  "extends": "../.claudelintrc.json",
  "rules": {
    "claude-md-size": "warn"
  }
}
```

**Node modules:**

```json
{
  "extends": "@company/claudelint-config"
}
```

**Multiple extends:**

```json
{
  "extends": ["./base.json", "./strict.json"]
}
```

**Built-in presets:**

claudelint ships with three built-in presets you can use directly:

```json
{
  "extends": "claudelint:recommended"
}
```

* `claudelint:recommended` - A curated subset of rules focused on correctness, security, and broad applicability. Best for most projects. This is the default when no config file is present.
* `claudelint:strict` - Everything in recommended, plus additional quality and best-practice rules. Good for teams that want stricter guardrails.
* `claudelint:all` - Every rule at its source-defined severity. Maximum coverage for comprehensive audits.

You can extend a preset and override individual rules:

```json
{
  "extends": "claudelint:recommended",
  "rules": {
    "skill-missing-changelog": "off",
    "skill-body-too-long": "error"
  }
}
```

::: tip
claudelint defaults to the **recommended** preset. Run `claudelint init` to choose a different preset, or use `--preset all` for maximum coverage.
:::

**Merge behavior:**

When extending configs, claudelint merges configurations in this order:

1. Base config (first in extends array)
2. Additional extended configs (in order)
3. Current config (overrides everything)

Rules are deep merged (child can override specific rules). Overrides and ignore patterns are concatenated. Circular dependencies are detected and prevented.

See [Monorepo documentation](/integrations/monorepos) for detailed examples.

### Rules

Rules can be configured with a severity level or a full configuration object:

```json
{
  "rules": {
    "claude-md-size": "warn",
    "claude-md-import-missing": "off"
  }
}
```

Severity levels:

* `"off"` - Disable the rule
* `"warn"` - Treat violations as warnings
* `"error"` - Treat violations as errors

For rules that support options:

```json
{
  "rules": {
    "claude-md-size": {
      "severity": "warn",
      "options": {
        "maxSize": 50000
      }
    }
  }
}
```

### Available Rules

See the [Rules Reference](/rules/overview) for the complete list of available rules, or run `claudelint list-rules`.

### Overrides

Override rules for specific file patterns. Patterns are relative to the configuration file's directory and include hidden directories such as `.claude`. Inherited overrides use the consuming configuration's directory; later matching overrides win. For an API configuration object, patterns are relative to the linter's `cwd`.

```json
{
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "rules": {
        "claude-md-size": "off"
      }
    },
    {
      "files": [".claude/skills/**/SKILL.md"],
      "rules": {
        "claude-md-size": "off"
      }
    }
  ]
}
```

### Ignoring Files

Patterns to exclude from linting (in addition to `.claudelintignore`):

```json
{
  "ignorePatterns": ["**/*.generated.ts", ".cache/", "coverage/"]
}
```

### Output Options

Configure output formatting:

```json
{
  "output": {
    "format": "stylish",
    "verbose": false,
    "color": true
  }
}
```

Options:

* `format` - Output format: `"stylish"`, `"json"`, `"compact"`, or `"sarif"`
* `verbose` - Enable verbose output
* `color` - Enable/disable color output (auto-detected by default)

### Inline Disables

You can disable rules for specific files, lines, or blocks using HTML comments, and optionally report unused disable directives. See [Inline Disable Directives](./inline-disables.md) for syntax, examples, and the `reportUnusedDisableDirectives` option.

### Max Warnings

Exit with error if warning count exceeds this threshold:

```json
{
  "maxWarnings": 10
}
```

Set to `0` to fail on any warning. Omit the field to allow unlimited warnings.

The CLI `--max-warnings` option overrides this config value:

```bash
# Override config maxWarnings with CLI option
claudelint check-all --max-warnings 5

# Allow unlimited warnings (ignores config)
claudelint check-all --max-warnings 0
```

## package.json Configuration

You can also configure claudelint in your `package.json`:

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "claudelint": {
    "rules": {
      "claude-md-size": "off"
    }
  }
}
```

## .claudelintignore

See [File Discovery — Ignoring Files](./file-discovery.md#ignoring-files) for `.claudelintignore` syntax, `.gitignore` integration, and default ignores.

## CLI Overrides

Config file settings can be overridden with CLI flags (`--config`, `--format`, `--strict`, `--max-warnings`, `--rule`). See the [CLI Reference](./cli-reference.md) for all commands and options.

## Example Configuration

Complete example `.claudelintrc.json`:

```json
{
  "rules": {
    "claude-md-size": "warn",
    "claude-md-import-missing": "error",
    "claude-md-import-circular": "error",
    "skill-missing-shebang": "warn",
    "skill-dangerous-command": "error"
  },
  "overrides": [
    {
      "files": ["*.test.ts"],
      "rules": {
        "claude-md-size": "off"
      }
    }
  ],
  "ignorePatterns": ["**/*.generated.ts", ".cache/"],
  "output": {
    "format": "stylish",
    "verbose": false,
    "color": true
  },
  "reportUnusedDisableDirectives": true,
  "maxWarnings": 10
}
```

## Hierarchical Configuration

claudelint searches for configuration files starting from the current directory and walking up the directory tree. This allows for:

* Project-level configuration in the project root
* Repository-level configuration in monorepo roots
* Global configuration in home directory

The first configuration file found is used. Files lower in the tree take precedence over files higher up.

## Programmatic API

claudelint exposes a programmatic API for use in custom tooling and scripts:

```typescript
import { ClaudeLint } from 'claude-code-lint';
```

See the [API Overview](/api/overview) for full documentation, including the [ClaudeLint class](/api/claudelint-class), [functional API](/api/functional-api), and [recipes](/api/recipes).