nixjanitor

A Terminal User Interface (TUI) tool for cleaning up orphaned files in NixOS impermanence/persistence setups.

What is nixjanitor?

Totally vibe-coded !!!

When using NixOS with impermanence, it's easy to accumulate orphaned files in your persistence directory—files that are no longer actively used by your system configuration.

nixjanitor helps you identify and clean up these orphaned files through an interactive TUI:

• 🔍 Auto-detects active persistence paths from your NixOS configuration
• 📊 Displays orphaned files in an interactive checklist
• 🗑️ Safe deletion with optional trash (files moved to .trash/ instead of permanent deletion)
• 🌳 Tree view showing parent/child relationships between directories and files
• 🚀 Fast scanning with concurrent directory traversal
• ⚡ Dry-run mode to preview changes before applying them

Installation

Option 1: Direct run (no installation)

nix run github:tharoldD/nixjanitor

With flags:

nix run github:tharoldD/nixjanitor -- --dry-run --persist-root /persist

Option 2: User profile install

nix profile install github:tharoldD/nixjanitor
nixjanitor --help

Option 3: NixOS system package (flake-based configuration)

Add to your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nixjanitor.url = "github:tharoldD/nixjanitor";
  };

  outputs = { self, nixpkgs, nixjanitor, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      # ... your config ...
      environment.systemPackages = [
        nixjanitor.packages.${system}.default
      ];
    };
  };
}

Option 4: Via overlay

{
  inputs.nixjanitor.url = "github:tharoldD/nixjanitor";
  
  nixpkgs.overlays = [ inputs.nixjanitor.overlays.default ];
  
  environment.systemPackages = [ pkgs.nixjanitor ];
}

Usage

Basic usage

nixjanitor

The tool will:

1. Auto-detect your persistence root (/persist, /nix/persist, or /persistent)
2. Auto-detect active paths from your NixOS configuration
3. Scan for all files in the persistence directory
4. Display orphaned files in an interactive checklist
5. Allow you to select files for deletion

CLI Flags

nixjanitor [OPTIONS]

Options:
  --persist-root string    Path to persistence storage (auto-detected if empty)
  --hostname string        NixOS config hostname (auto-detected if empty)
  --dry-run               Show what would be deleted without deleting
  --no-trash              Delete directly instead of moving to trash

Examples

Dry-run mode (safe preview):

nixjanitor --dry-run

Specify persistence root:

nixjanitor --persist-root /mnt/persist

Delete permanently (skip trash):

nixjanitor --no-trash

Specify hostname for configuration detection:

nixjanitor --hostname my-laptop

TUI Navigation

Once in the TUI:

• ↑/↓ or j/k: Navigate through the file list
• Space: Toggle selection for deletion
• Enter: Expand/collapse directories
• Tab: Jump to next section
• d: Start deletion of selected items
• q: Quit

How it works

1. Detection Phase

nixjanitor detects active persistence paths using two methods:

Primary method (recommended): Parses your NixOS configuration via nix eval:

nix eval /etc/nixos#nixosConfigurations.<hostname>.config.environment.persistence --json

Fallback method: Parses /proc/self/mountinfo to find bind mounts.

2. Scanning Phase

• Recursively scans the persistence directory
• Skips the .trash/ directory (used for safe deletion)
• Builds a tree structure of files and directories
• Marks files as "orphaned" if they're not in the active paths list

3. Cleanup Phase

• Moves selected files to .trash/ by default (can be permanently deleted with --no-trash)
• Shows progress for each file being cleaned
• Handles errors gracefully (e.g., permission denied)

Requirements

• NixOS with a persistence setup (e.g., using impermanence)
• Nix flakes enabled (for configuration detection)
• Linux (uses /proc/self/mountinfo for fallback detection)
• Root directory mounted as tmpfs or similar ephemeral filesystem

Recommended setup

This tool is designed for NixOS systems using impermanence patterns like:

{
  environment.persistence."/persist" = {
    directories = [
      "/etc/nixos"
      "/var/log"
      "/var/lib/systemd"
    ];
    files = [
      "/etc/machine-id"
    ];
    users.youruser = {
      directories = [
        "Documents"
        "Downloads"
        ".config/nvim"
      ];
      files = [
        ".ssh/id_ed25519"
      ];
    };
  };
}

Development

Build from source

git clone https://github.com/tharoldD/nixjanitor.git
cd nixjanitor
go build -o nixjanitor

Development shell

With flakes:

nix develop

Legacy nix-shell (delegates to flake):

nix-shell

The development environment includes:

• Go 1.26.3
• gopls (language server)
• go-tools (staticcheck, etc.)

Project structure

nixjanitor/
├── main.go                 # Entry point, CLI parsing
├── internal/
│   ├── app/               # Bubble Tea TUI model & state machine
│   │   ├── model.go       # Main model & update logic
│   │   ├── states.go      # 6-state pipeline
│   │   └── styles.go      # Lipgloss styling
│   ├── detect/            # Active path detection
│   │   └── detect.go      # nix eval + /proc/self/mountinfo parsing
│   ├── scanner/           # Filesystem scanning
│   │   └── scanner.go     # Recursive directory walker
│   └── cleanup/           # Deletion logic
│       └── cleanup.go     # Move to trash or delete
├── flake.nix              # Nix flake definition
├── go.mod                 # Go module dependencies
└── README.md              # This file

Built with

• AI Agents.
• Bubble Tea v2 - TUI framework
• Lip Gloss v2 - Terminal styling
• Bubbles v2 - TUI components