claudelint

Appearance

Claude Code Hooks ​

claudelint can automatically validate your Claude Code project when a session starts using Claude Code hooks.

How It Works ​

SessionStart command hooks run a shell command when a Claude Code session begins. The command's stdout is fed into Claude's context — not displayed in your terminal. This means Claude is silently made aware of any validation issues and can proactively mention them when you start chatting.

Quick Setup ​

Run claudelint init with the --hooks flag to create the hook file automatically:

claudelint init --hooks

Manual Setup ​

Alternatively, create .claude/hooks/hooks.json in your project manually:

json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx claudelint check-all --format json"
          }
        ]
      }
    ]
  }
}

When you start a Claude Code session, the hook runs claudelint check-all in the background. Claude receives the JSON results and can inform you about any errors or warnings in your project's Claude Code configuration.

The --format json flag produces structured output that is easy for Claude to parse and act on.

Alternative: Prompt Hook ​

If you want Claude to actively run validation and report results (instead of receiving them silently), use a prompt hook:

json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Run npx claudelint check-all and briefly report any issues."
          }
        ]
      }
    ]
  }
}

This costs an extra turn at session start — Claude will run the command itself and show you the results before you begin working.

Troubleshooting ​

Hook doesn't run ​

Problem: The SessionStart hook doesn't execute when you start a Claude Code session.

Solution:

  1. Check that claudelint is installed globally or in your project
  2. Verify the command works manually: claudelint check-all --format json
  3. Check hook syntax in .claude/hooks/hooks.json
  4. Ensure event names are PascalCase (e.g., SessionStart, not session-start)

Too many warnings ​

Problem: The hook produces a large volume of warnings that clutter Claude's context.

Solution:

  1. Configure rules in .claudelintrc.json to disable noisy rules
  2. Use .claudelintignore to skip large or irrelevant directories

See Also ​