impermanence-audit

name	impermanence-audit
description	Audit NixOS impermanence state — find files still on the current filesystem device. Use when the user wants to check for untracked files, audit impermanence, or runs /impermanence-audit.
allowed-tools	Bash(sudo:*), Bash(bash:*), Bash(nix:*), Read, Edit, Glob, Grep

Impermanence Audit

Scan the root filesystem with find -xdev and identify files still on the same device as /. These files would be lost on reboot when impermanence resets the root filesystem.

Workflow

1. Run the audit script

sudo impermanence-audit efficacy38

Interface:

• Users are optional positional arguments, for example sudo impermanence-audit efficacy38 gaming.
• With no users, it audits system paths only.
• The script only relies on find -xdev plus device-number filtering.
• It always emits JSON.

2. Analyze results

Review the untracked files and categorize them:

Category	Action
Application state/config	Add to the appropriate feature module's environment.persistence
Transient/cache files	Safe to ignore — add to ~/.config/impermanence-audit/ignore if noisy
System service data	Add to the system module (usually features/system/boot.nix)
Unknown	Investigate what created the file before deciding

3. Add missing persistence declarations

Persistence paths are declared across feature modules. Match the file to its feature:

Path pattern	Module file
Desktop app configs (~/.config/app, ~/.local/share/app)	flake-modules/modules/features/desktop/common.nix
Dev tools (~/.kube, .local/share/direnv, etc.)	flake-modules/modules/features/devpack/tools.nix
Editor data (~/.local/share/nvim)	flake-modules/modules/features/devpack/editor.nix
System services (/var/lib/*, /etc/*)	flake-modules/modules/features/system/boot.nix
KDE state	flake-modules/modules/features/desktop/kde.nix
Steam/gaming	flake-modules/modules/features/desktop/steam.nix
Browser profiles	flake-modules/modules/features/desktop/zen.nix

The pattern for adding a user directory to a feature module:

# Inside the module's config block, guarded by impermanence check:
config = lib.mkIf (cfg.enable && config.my.system.impermanence.enable) {
  environment.persistence."/persistent/system".users."efficacy38" = {
    directories = [
      ".config/new-app"
      ".local/share/new-app"
    ];
  };
};

For system-level paths:

environment.persistence."/persistent/system" = {
  directories = [
    "/var/lib/new-service"
  ];
};

4. Rebuild and verify

After adding persistence declarations:

nh os switch --hostname=stella

Then re-run the audit to confirm the paths are now covered.