Python Linter Integration - Hooks

This hook runs after Claude Code successfully uses a matching file-editing tool. It checks only edited .py files and uses the first available linter in this order: pylint, flake8, then pycodestyle.

It does not install a linter for you, aggregate multiple tools, run ruff, or calculate historical quality trends. Install and configure the linter you want the hook to use before enabling it.

Installation

Create the hook script:

mkdir -p .claude/hooks
touch .claude/hooks/python-linter-integration.sh
chmod +x .claude/hooks/python-linter-integration.sh

Save the script from this entry to .claude/hooks/python-linter-integration.sh.

Add this to .claude/settings.json for a project-wide hook, or to ~/.claude/settings.json for a personal hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/python-linter-integration.sh"
          }
        ]
      }
    ]
  }
}

Hook Script

#!/usr/bin/env bash
set -euo pipefail

INPUT="$(cat)"
FILE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')"

if [ -z "$FILE_PATH" ] || [ "${FILE_PATH##*.}" != "py" ]; then
  exit 0
fi

if [ ! -f "$FILE_PATH" ]; then
  echo "Python linter hook skipped: file not found: $FILE_PATH"
  exit 0
fi

if command -v pylint >/dev/null 2>&1; then
  pylint "$FILE_PATH" --score=yes --reports=no --msg-template="{line}:{column}: {category}: {msg} ({symbol})"
elif command -v flake8 >/dev/null 2>&1; then
  flake8 "$FILE_PATH" --max-line-length=88
elif command -v pycodestyle >/dev/null 2>&1; then
  pycodestyle "$FILE_PATH" --max-line-length=88
else
  echo "Python linter hook skipped: install pylint, flake8, or pycodestyle."
fi

Requirements

• Claude Code with hooks enabled.
• jq available on PATH so the script can read hook input JSON.
• At least one supported linter installed: pylint, flake8, or pycodestyle.

Source Verification Notes

Verified on 2026-06-19:

• Claude Code hooks are user-defined shell commands, HTTP endpoints, or prompts that run at lifecycle events such as PostToolUse.
• The hooks reference documents command hooks receiving JSON on stdin and using matcher groups to narrow which tool calls trigger a handler.
• This entry combines that hook mechanism with documented Python linter command invocations. The hook itself is a local recipe, not an official bundled hook.

Troubleshooting

• If the hook never fires, confirm the event key is PostToolUse and the matcher covers the edit tool names used by your Claude Code version.
• If the hook fires but skips every file, inspect the hook input shape and adjust the jq path for the edited file.
• If lint output is too noisy, configure the selected linter with its normal project config file instead of adding more logic to the hook.

• Source repositorygithub.com 2026-07-13T15:19:32-07:00
• Documentationcode.claude.com