chezmoi-drift

name	chezmoi-drift
description	Read-only chezmoi dotfile management assistant. Use when the operator asks about their chezmoi-managed dotfiles, including: (1) listing managed or unmanaged files, (2) checking for drift between actual files and chezmoi's target state, (3) inspecting what chezmoi would change, (4) understanding chezmoi status output, (5) reviewing chezmoi configuration or template data. Triggers on questions like "what files does chezmoi manage", "have my dotfiles drifted", "what would chezmoi change", "show me unmanaged files", "chezmoi status", or any dotfile inventory/drift inquiry. CRITICAL: This skill is strictly read-only. Never run mutating chezmoi commands.
context	fork

Chezmoi Drift Detection (Read-Only)

Safety Constraint

NEVER run any chezmoi command that mutates state. The following are FORBIDDEN:

apply, add, manage, edit, edit-config, edit-config-template, edit-encrypted, forget, unmanage, destroy, remove, rm, re-add, merge, merge-all, import, init, update, purge, chattr, git, state set, state delete, state delete-bucket, state reset, encrypt, decrypt, upgrade, ssh, docker

If the operator needs a mutating action, explain what command they would run and let them do it.

Quick Audit Script

For a full diagnostic pass (health, drift, asset counts) with pretty output, run:

uvx --from .claude/skills/chezmoi-drift chezmoi-audit              # health + drift summary
uvx --from .claude/skills/chezmoi-drift chezmoi-audit --drift       # also show full diff
uvx --from .claude/skills/chezmoi-drift chezmoi-audit --managed     # also list all managed entries
uvx --from .claude/skills/chezmoi-drift chezmoi-audit --all         # everything
uvx --from .claude/skills/chezmoi-drift chezmoi-audit --report      # structured JSON for Claude
uvx --from .claude/skills/chezmoi-drift chezmoi-audit --report 2>/dev/null  # suppress build noise

Fallback (plain text, no dependencies beyond chezmoi):

bash scripts/chezmoi-audit.sh          # config + health + drift summary
bash scripts/chezmoi-audit.sh --drift   # also show full diff
bash scripts/chezmoi-audit.sh --managed # also list all managed entries
bash scripts/chezmoi-audit.sh --all     # everything

All script paths are relative to this skill's directory.

Workflow

For targeted queries, determine the operator's intent and follow the appropriate path:

"What does chezmoi manage?" --> Enumerate assets "Have my dotfiles drifted?" --> Detect drift "What files aren't managed?" --> Find unmanaged files "Show me details about X" --> Inspect specific targets "Analyze my chezmoi config" --> Run the audit script

Enumerate Managed Assets

# All managed entries
chezmoi managed

# Filter by type
chezmoi managed --include=files
chezmoi managed --include=dirs
chezmoi managed --include=symlinks
chezmoi managed --include=files,symlinks

# Scoped to a directory
chezmoi managed ~/.config

# Show source-relative paths (shows the encoded filenames in source dir)
chezmoi managed --path-style=source-relative

# JSON output for structured processing
chezmoi managed --format=json

Detect Drift

Three commands, from quick to detailed:

# 1. Pass/fail check (exit code 0=clean, 1=drift)
chezmoi verify

# 2. Status summary (like git status)
chezmoi status

# 3. Full diff
chezmoi diff

Reading chezmoi status Output

Two-column format per entry. Column 1 = changes since chezmoi last wrote. Column 2 = what apply would do.

Char	Col 1 meaning	Col 2 meaning
Space	No change	No change
A	Entry was created	Entry will be created
D	Entry was deleted	Entry will be deleted
M	Entry was modified	Entry will be modified
R	N/A	Script will be run

Example: M .bashrc means .bashrc was modified locally since chezmoi last applied it, and apply would not change it (second column is space). M .bashrc means .bashrc differs from chezmoi's target and apply would overwrite it.

Find Unmanaged Files

# All unmanaged files in home directory (can be noisy)
chezmoi unmanaged

# Scoped to specific directories (recommended)
chezmoi unmanaged ~/.config
chezmoi unmanaged ~/.ssh ~/.config/git

Inspect Specific Targets

# What chezmoi thinks a file should contain
chezmoi cat ~/.bashrc

# Full target state as JSON
chezmoi dump ~/.bashrc
chezmoi dump --format=yaml

# Where the source file lives
chezmoi source-path ~/.bashrc

# Template data available to chezmoi
chezmoi data
chezmoi data --format=yaml

Diagnostics

# Health check
chezmoi doctor

# Current configuration
chezmoi cat-config
chezmoi dump-config

# Ignored entries
chezmoi ignored

Chezmoi Concepts Reference

See references/concepts.md for source state attributes, naming conventions, and key terminology.

Presenting Results

When reporting to the operator:

• For managed assets: present as a clean list, optionally grouped by directory
• For unmanaged files: note that these are files chezmoi does NOT track; the operator decides whether to add them
• Always clarify what the operator would need to run if they want to fix drift (e.g., chezmoi apply or chezmoi add), but never run those commands

Drift Report Format

Preferred workflow: Run chezmoi-audit --report to get pre-analyzed JSON with grouped items, risk classifications, diff summaries, and remediation commands. Use this output to populate the drift report format below, adding human-readable interpretation and judgment. Only fall back to manual chezmoi status + chezmoi diff when the script is unavailable.

For drift detection, always use this structured format:

a) Summary Table

Lead with a count ("N entries differ from target state"), then a markdown table with one row per logical drift item. Group related entries (e.g. an entire .git/ tree) into a single row.

Columns:

Column	Description
#	Sequential number for cross-referencing
Path	File or directory path (use trailing / for directories)
Status	Two-character chezmoi status code (e.g. MM, DA)
Direction	Human-readable description of what changed and which side is newer
Risk	HIGH, MEDIUM, or LOW

Risk levels:

• HIGH: Active config that affects keyboard, terminal, editor, or shell behavior. Blindly applying could break the operator's workflow.
• MEDIUM: Tooling config, paths, or system prompts where the wrong choice could cause subtle breakage.
• LOW: Ephemeral runtime data (databases, lock files) or stale scaffolding that shouldn't be managed.

b) Per-Item Detail

For each row in the summary table, include a markdown header (### N. path) followed by:

• A plain-English description of what the diff contains (what changed, in which direction, and why it matters)
• For text files, call out specific additions/removals worth noting
• For binary files, note that they're binary and whether they're ephemeral

c) Remediation Commands

Under each item's detail section, provide a concrete markdown list of commands the operator can run. Always include both directions where applicable:

• chezmoi diff <path> -- review the full diff
• chezmoi apply <path> -- accept the target state (overwrite local)
• chezmoi add <path> -- keep local state as source of truth
• chezmoi forget <path> -- stop tracking (for files that shouldn't be managed)

For items that need investigation first (e.g. checking if a directory exists), include the investigative command before the chezmoi commands.

d) Risk Assessment

Close the report with a Risk Assessment section that groups items by risk level and provides actionable guidance:

• HIGH RISK: Explain what could break and advise reviewing diffs before acting.
• MEDIUM RISK: Explain the tradeoff and advise deciding per-file.
• LOW RISK / Noise: Recommend chezmoi forget and note how many drift entries this would eliminate.