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

{
  "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:

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

Node modules:

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

Multiple extends:

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

Built-in presets:

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

{
  "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:

{
  "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 for detailed examples.

Rules

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

{
  "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:

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

Available Rules

See the Rules Reference for the complete list of available rules, or run claudelint list-rules.

Overrides

Override rules for specific file patterns:

{
  "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):

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

Output Options

Configure output formatting:

{
  "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 for syntax, examples, and the reportUnusedDisableDirectives option.

Max Warnings

Exit with error if warning count exceeds this threshold:

{
  "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:

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

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

.claudelintignore

See File Discovery — 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 for all commands and options.

Example Configuration

Complete example .claudelintrc.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:

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

See the API Overview for full documentation, including the ClaudeLint class, functional API, and recipes.