claudelint

Appearance

Configuration ​

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

Quick Navigation ​

Configuration Topics:

Common Tasks:

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 two 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.
  • claudelint:all - Every rule at its source-defined severity. Equivalent to running with no config file, but explicit.

You can extend a preset and override individual rules:

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

TIP

Running claudelint init will prompt you to choose between Recommended, All, or Manual configuration.

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:

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 for the complete list of available rules, or run claudelint list-rules.

Overrides ​

Override rules for specific file patterns:

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)

Report Unused Disable Directives ​

Report when inline disable comments don't suppress any violations:

json
{
  "reportUnusedDisableDirectives": true
}

When enabled, claudelint warns about:

  • Disable directives that don't match any violations
  • Directives for rules that don't trigger in that location
  • Leftover disables after violations are fixed

Example:

markdown
<!-- claudelint-disable-next-line size-error -->

Normal line with no violation - will warn about unused disable

Why use this:

  • Keeps inline disable comments clean and intentional
  • Identifies when violations have been fixed
  • Prevents confusion about which rules are actually active

See Inline Disable Directives for complete documentation on disable syntax and usage.

Inline Disable Comments ​

You can disable specific rules for individual files, lines, or blocks using HTML comments. See Inline Disable Directives for full syntax, examples, and best practices.

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 ​

Create a .claudelintignore file to exclude files and directories from linting:

text
# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/

# Generated files
**/*.generated.ts

# Test fixtures
fixtures/

Syntax is similar to .gitignore:

  • # for comments
  • * matches any characters except /
  • ** matches any characters including /
  • Trailing / matches directories
  • Blank lines are ignored

Default ignores (always applied):

  • node_modules/**
  • .git/**
  • dist/**
  • build/**

CLI Options ​

Configuration file settings can be overridden with CLI flags like --config, --format, --strict, and --max-warnings. See the CLI Reference for complete documentation of all commands and options.

CLI Rule Overrides ​

The --rule flag lets you override rule severity directly from the command line, without editing your config file:

bash
# Override a single rule
claudelint check-all --rule skill-name:error

# Override multiple rules
claudelint check-all --rule skill-name:error --rule claude-md-size:off

# Disable a rule temporarily
claudelint check-all --rule skill-missing-version:off

The format is rule-id:severity where severity is off, warn, or error. CLI overrides take the highest precedence, above both config files and extends chains.

To debug configuration issues, use print-config, validate-config, and resolve-config. See CLI Reference - Config Management for details.

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 for full documentation, including the ClaudeLint class, functional API, and recipes.