Docker Doctor

Your Dockerfiles are probably wrong. Docker Doctor finds out why.

Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 33 rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.

Works with any project that uses Docker.

Website →

What it catches

The most common finding: an install that sits below the source copy, so editing any file reruns it.

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm ci
CMD ["node", "server.js"]

⚠ WARN [docker-doctor/order-layers]:4
      3 │ COPY . .
>     4 │ RUN npm ci
      5 │ CMD ["node", "server.js"]

  Running package installation command 'npm ci' after copying application files (at line 3). This invalidates the cache on any code changes.
  Help: Copy dependency definition files (like package.json, lockfiles) and run install commands BEFORE copying the rest of the application source code.

Manifest first, install, then the source — plus a .dockerignore, so a stray log file or a local node_modules cannot invalidate that layer either:

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

Four lines reordered and one new file takes that Dockerfile from 77 to 87, with the Performance category down to zero.

Install

1. Quick start

npx @docker-doctor/cli@latest

2. Install for agents

Once you have an audit, install the skill so your coding agent learns the /docker-doctor triage workflow and can fix the issues for you:

npx @docker-doctor/cli@latest install

Works with Claude Code, Cursor, Codex, OpenCode, and many more. After an interactive scan finds issues, Docker Doctor also offers to hand them straight to an agent detected on your machine. Add --global to install the skill once for your whole machine instead of the current project.

Prefer plugins? This repository is also a Claude Code plugin marketplace and ships a Cursor plugin — both bundle all three skills (docker-doctor, docker-author, improve-docker) and update with the repo:

/plugin marketplace add PunGrumpy/docker-doctor
/plugin install docker-doctor@docker-doctor

Rules reference →

3. Run in Docker Sandboxes

Running coding agents unattended in Docker Sandboxes? The Docker Doctor kit preinstalls the CLI and skill in every sandbox and tells the agent to lint its own Dockerfile and Compose changes before committing:

sbx run --kit docker.io/pungrumpy/docker-doctor-kit:latest claude

See kits/docker-doctor for what the kit installs and how it works.

4. Run in CI

The GitHub Action (PunGrumpy/docker-doctor) scans every pull request and posts a sticky summary comment — advisory by default, with an opt-in gate. See the GitHub Actions guide for setup, inputs, and gating.

5. Configure

// docker-doctor.config.ts
import type { DockerDoctorConfig } from "@docker-doctor/cli";

export default {
  rules: {
    "docker-doctor/no-root-user": "error",
  },
} satisfies DockerDoctorConfig;

Prefer YAML? docker-doctor.config.yaml works too, with editor autocomplete via # yaml-language-server: $schema=https://docker-doctor.vercel.app/schema.json. A defineConfig helper is also exported for projects with @docker-doctor/cli installed — see the configuration docs.

How the score works

Every scan that analyzes at least one file produces a 0-100 health score alongside a label (Excellent 🏆, Good ✅, Needs Work ⚠️, Critical 🚨). A file counts as analyzed when docker-doctor parsed it and the rules have something to check in it. A Dockerfile needs at least one instruction. A Compose file needs at least one service, a top-level models entry or a version key. When no file qualifies, there is no score.

Each diagnostic adds a penalty based on severity:

Severity	Penalty
error	10
warning	4
info	1

The penalties are added up and divided by the number of Dockerfiles and Compose files docker-doctor analyzed, so the score describes a typical file. The score is then computed as an asymptotic decay curve rather than a simple subtraction:

score = round(100 * e^(-penalty / K))   // K = 70

A project with no diagnostics always scores exactly 100. As the average penalty grows, the score falls toward 0 without a hard floor. Rounding gives 0 once the average penalty reaches about 371 per file, which is roughly 37 errors in every file. Below that, the score keeps responding to fixes, though one small finding in a large project can round away. K = 70 was chosen so a single warning (penalty 4) still lands around 94, inside the Excellent bucket, while errors and repeated warnings continue to erode the score.

The average can hide one bad file among many good ones. The exit code does not depend on the score, so an error-severity finding in any file still fails the scan.

The label thresholds are unchanged: >= 90 Excellent, >= 75 Good, >= 50 Needs Work, otherwise Critical.

API

import { discoverProject, toJsonReport } from "@docker-doctor/cli";
import type { Diagnostic } from "@docker-doctor/cli";

Contributing

MIT and Issues welcome!