Hadolint Dockerfile Diagnostics Hook for Claude Code

Overview

This hook runs Hadolint after Claude Code writes or edits a Dockerfile-like file. It is intentionally read-only: it reports diagnostics and exits non-zero when Hadolint reports findings, but it does not build images, run containers, pull base images, install packages, rewrite Dockerfiles, or execute Dockerfile instructions.

Use it when a project contains Dockerfiles and you want immediate feedback on Dockerfile best practices, inline shell in RUN instructions, pinned images, trusted registries, label policy, package manager usage, and project Hadolint configuration after Claude edits a file.

Source Review

• https://hadolint.github.io/hadolint/
• https://github.com/hadolint/hadolint
• https://github.com/hadolint/hadolint/blob/master/README.md
• https://raw.githubusercontent.com/hadolint/hadolint/master/README.md

These sources were reviewed on 2026-06-04. The official Hadolint README describes Hadolint as a Dockerfile linter that parses Dockerfiles into an AST, applies rules, and uses ShellCheck for Bash inside RUN instructions. It also documents local binary use, Docker and Podman invocation options, CLI output formats, ignored rules, trusted registries, label checks, severity thresholds, and configuration file lookup.

Installation

1. Install Hadolint locally through an operating system package manager or the official Hadolint release path.
2. Confirm hadolint --help works in the same environment Claude Code uses.
3. Confirm jq is available.
4. Save the script as .claude/hooks/hadolint-dockerfile-diagnostics.sh.
5. Make it executable.
6. Add the hook configuration to .claude/settings.json or user settings after reviewing the behavior with your team.

Hook Configuration

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/hadolint-dockerfile-diagnostics.sh"
          }
        ]
      }
    ]
  }
}

Hook Script

Save this as .claude/hooks/hadolint-dockerfile-diagnostics.sh and make it executable:

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

input="$(cat)"

if ! command -v jq >/dev/null 2>&1; then
  echo "Hadolint hook skipped: jq is required to parse Claude Code hook input." >&2
  exit 0
fi

tool_name="$(printf '%s' "$input" | jq -r '.tool_name // .toolName // empty')"
file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.path // .toolInput.file_path // .toolInput.path // empty')"

case "$tool_name" in
  Write|Edit|MultiEdit|write|edit|multiedit) ;;
  *) exit 0 ;;
esac

if [ -z "$file_path" ] || [ ! -f "$file_path" ] || [ ! -r "$file_path" ]; then
  exit 0
fi

file_name="$(basename "$file_path")"
case "$file_name" in
  Dockerfile|Dockerfile.*|*.Dockerfile|*.dockerfile|Containerfile|Containerfile.*|*.Containerfile|*.containerfile) ;;
  *) exit 0 ;;
esac

if ! command -v hadolint >/dev/null 2>&1; then
  echo "Hadolint hook skipped: install hadolint to enable Dockerfile diagnostics." >&2
  exit 0
fi

echo "Hadolint hook: checking $file_path" >&2
hadolint --format gnu "$file_path"
status=$?

if [ "$status" -ne 0 ]; then
  echo "Hadolint hook: diagnostics found. Review Dockerfile rules, inline shell, pinned images, labels, and trusted registry policy before asking Claude to continue." >&2
fi

exit "$status"

What It Checks

• Dockerfile-like files such as Dockerfile, Dockerfile.prod, service.Dockerfile, and Containerfile.
• Hadolint's Dockerfile rules and output in gnu format.
• Inline shell diagnostics for Bash code inside RUN instructions through Hadolint's ShellCheck-backed behavior.
• Project-level Hadolint configuration when present and discoverable by the Hadolint binary.

What It Does Not Do

• It does not build images.
• It does not run Docker, Podman, or containerized Hadolint.
• It does not pull base images or contact registries.
• It does not install Hadolint.
• It does not rewrite Dockerfiles or apply auto-fixes.
• It does not scan image layers, packages, CVEs, SBOMs, or runtime capabilities.
• It does not approve secrets, credentials, private registries, or production deployment settings.

Troubleshooting

Hook says Hadolint is missing

Install Hadolint through an operating system package manager, official release, or another reviewed local installation path. Confirm command -v hadolint works in the same shell environment Claude Code uses.

Hook does not run for a Dockerfile

This script intentionally matches Dockerfile-like basenames. Rename generated or custom files to a recognized Dockerfile pattern, or extend the case statement after reviewing the project naming convention.

Hadolint reports findings that the team intentionally ignores

Prefer a reviewed project Hadolint configuration or scoped inline ignore comments. Keep ignored rules visible in review so the team understands why a rule is suppressed.

Dockerfile passes but the image is still unsafe

Hadolint is static Dockerfile analysis. Pair it with image builds, vulnerability scans, SBOM review, secret scanning, runtime user checks, and registry policy where those controls matter.

Duplicate Check

No existing content/hooks, content/skills, content/agents, content/mcp, or content/tools entry in this checkout matches Hadolint, hadolint/hadolint, hadolint.github.io, or a Dockerfile diagnostics hook. Open PR titles, branch names, changed files, issue titles, issue bodies, and source URLs were also checked before drafting this entry.

This entry is distinct from the existing ShellCheck hook. ShellCheck is focused on shell scripts; this hook is focused on Dockerfile best-practice diagnostics and Hadolint's Dockerfile parser/rule set, while still benefiting from Hadolint's ShellCheck-backed RUN instruction analysis.

Editorial Disclosure

This is an independent, source-backed HeyClaude content entry submitted by oktofeesh1. It is not sponsored by Hadolint or the Hadolint maintainers. The hook expects a user-installed Hadolint binary and does not package, redistribute, or verify a Hadolint release artifact.