kdrift 0.1.3

CLI, MCP, LSP, and VS Code extension for kustomize manifest drift detection

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/base/deployment.yaml    # diff overlays affected by this file
kdrift diff --overlay k8s/dev           # diff only this overlay
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

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