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

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)
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

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.

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