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.

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