kdrift

CLI, MCP, LSP, and VS Code extension for kustomize manifest drift detection. Discovers which overlays are affected by your changes, renders baselines and candidates, and diffs per-resource.

Install

uv tool install kdrift
# or: pip install kdrift

Requires Python 3.13+ and kustomize on PATH.

For unreleased changes on main:

uv tool install git+https://github.com/mikedougherty/kdrift

Usage

kdrift diff                             # diff all affected overlays vs HEAD
kdrift diff k8s/staging                 # diff only the staging overlay (see Scoping)
kdrift diff k8s/dev k8s/staging         # diff several named overlays
kdrift diff k8s/base/deployment.yaml    # diff overlays affected by this file
kdrift diff --overlay k8s/dev           # force-diff one overlay, even with no changes
kdrift diff --ref main~3                # diff against a specific ref
kdrift diff --ref main~5..main~2        # compare two commits
kdrift diff -C /path/to/repo            # target a different repository
kdrift diff --format json               # structured JSON output
kdrift diff --check                     # exit non-zero if drift exists (CI/pre-commit)
kdrift diff --watch                     # continuous mode: re-diff on file save
kdrift --version                        # print the installed version
kdrift version                          # same, as a subcommand

Scoping with PATHS

The positional PATHS narrow which overlays are reported. They do not work like a git pathspec on changed files — scoping to one environment never hides drift that reaches it through a shared base.

• A path selects an overlay when it names the overlay directory (or an ancestor), a file inside the overlay, or an upstream input the overlay depends on (a shared base/ or component).
• Selection runs against the full set of overlays affected by all your changes. So kdrift diff k8s/staging still reports staging when the only change is in k8s/base/ that staging consumes.
• A path that matches nothing, or that selects an overlay with no drift, is reported in warnings (JSON) / on stderr — an empty result is never silently read as "no drift".
• --overlay is different: it force-diffs exactly one overlay regardless of what changed, and takes precedence over PATHS.

How It Works

1. git diff --name-only HEAD finds changed files
2. Dependency graph maps changes to affected leaf overlays (parses all kustomization.yaml reference types, including helm chart directories and the other local-file inputs that change a render)
3. kustomize build renders baseline (via git worktree, cached) and candidate (working tree)
4. Two-phase per-resource diff: exact GVK+namespace+name match, then generator-aware matching for hash-suffixed ConfigMap/Secret names
5. Output as unified diff or structured JSON

Helm charts in another repo

If an overlay's chart source lives in a separate local git checkout (an absolute helmGlobals.chartHome, an escaping symlink, or a ../ escape), kdrift renders the baseline against a worktree of that repo at its HEAD so drift in the external chart shows up too — baseline = your repo at --ref + each external repo at its HEAD, vs the working trees. A chart source that can't be pinned (non-git, read-only, or resolving back into your repo) is reported in warnings rather than silently treated as clean. See docs/design/multi-repo-diff.md.

The chartHome redirect must exist at the baseline ref. The baseline is your consumer repo at --ref (default HEAD). If the helmGlobals.chartHome redirect to the local chart under test exists only in your working tree, the baseline still renders from the original source (e.g. an OCI repo:) while the candidate renders from the local chart — so the diff is "OCI chart vs local chart" (everything), not "my chart edit". Two ways to get a clean loop:

• Commit the redirect on a test branch, then iterate: point helmGlobals.chartHome at the local chart, commit on a throwaway branch of the consumer, and run kdrift diff as you edit the chart.
• Use --chart-home (no commit needed): kdrift diff --chart-home <kustomization-dir>=<path-to-local-charts> applies the redirect for that run only — to both the baseline worktree (redirected to the external repo at HEAD) and the candidate. It is opt-in and repeatable. To apply it to the candidate, kdrift briefly rewrites the live kustomization.yaml, then restores it to its exact original bytes; if the run is interrupted mid-render the file is left modified, but it is git-tracked, so git restore <file> recovers it. Not supported with --watch.

Configuration

Create .kdrift.yaml anywhere in your directory tree (searched upward from CWD):

kustomize_args:
  - "--enable-helm"
  - "--load-restrictor"
  - "LoadRestrictionsNone"
kustomize_binary: /usr/local/bin/kustomize  # optional, defaults to PATH
env:                                        # extra env vars for kustomize subprocess
  HELM_REGISTRY_TOKEN: "abc123"

All fields can be overridden via environment variables (KDRIFT_KUSTOMIZE_BINARY, KDRIFT_KUSTOMIZE_ARGS, KDRIFT_KUSTOMIZE_ENV_<NAME>). See the knowledge doc for details.

Development

make deps        # Install dependencies
make validate    # Run all checks (lint + typecheck + test)
make test        # Tests only
make typecheck   # mypy strict mode

See docs/development.md for detailed setup and the release process (release-please + RC publishing).

Quick Start: MCP Server for Claude Code

Give your AI agent kustomize drift detection in two steps:

1. Install kdrift:

uv tool install kdrift

2. Add to your Claude Code MCP config (.claude.json or project .mcp.json):

{
  "mcpServers": {
    "kdrift": {
      "command": "kdrift",
      "args": ["mcp"]
    }
  }
}

That's it. Your agent now has four tools: kdrift_diff, kdrift_discover, kdrift_affected, kdrift_render. Ask it to "check what my kustomize changes affect" and it will use them.

3. (Optional) Add agent instructions for deeper context on how to use kdrift:

@path/to/kdrift/docs/agents/AGENTS.md

Or copy docs/agents/ into your project's agent instructions directory. The files are self-contained and agent-agnostic.

Agent Integration

kdrift ships with agent-readable instructions in docs/agents/. These work with any AI coding assistant that supports AGENTS.md or similar instruction files.

VS Code Extension

The vscode-kdrift/ directory contains a VS Code extension that shows drift diffs in a side panel, modeled after the built-in Markdown Preview. See vscode-kdrift/README.md for setup and development.

LSP Server (IDE integration)

kdrift lsp          # stdio transport, configure in your LSP client
kdrift lsp --debug  # enable file logging to ~/.cache/kdrift/kdrift.log

Provides diagnostics on save, CodeLens annotations, and hover info.

Documentation

• Development Guide
• Configuration
• Agent Instructions