Custodian is a Windows disk usage analyzer for machines where you need fast, local inspection without depending on third-party desktop utilities. It ships as a self-updating desktop app, a portable desktop app, a full-screen terminal UI, and a CLI for repeatable server or workstation workflows.
- Find space quickly with folder trees, sortable detail grids, largest-file and largest-folder views, extension summaries, treemaps, pie charts, and bar charts.
- Switch between drives without losing context with a session scan cache that restores recent scan results, selected folder, detail mode, and chart scope while Custodian stays open. The Folder Map lists every drive and folder scanned in the session, so any of them is one click away.
- Choose the right scanner with Auto mode, recursive scanning for folders and network shares, and optional NTFS MFT scanning for local NTFS volumes.
- Scan cloud sync roots safely through provider-aware OneDrive, Nextcloud, and Dropbox targets that use local desktop-client metadata only and avoid intentional placeholder hydration.
- Inspect Android phone storage when Windows exposes an unlocked phone through USB File Transfer / MTP, with read-only metadata scans of each readable storage root plus safe copy-to-PC actions.
- Run in locked-down environments with a portable build, a CLI, UNC path support, a full-screen TUI, safe fallbacks when raw NTFS access is unavailable, and an optional always-open-as-administrator launch setting.
- Review before deleting with Recycle Bin management, restore, permanent delete, empty-bin actions, and confirmation prompts.
- Keep results portable with
.custodian-scanSQLite save files plus CSV and JSON export from the desktop app or CLI. - Handle untrusted scan data defensively with saved-scan validation before use, CSV formula neutralization, remote-path confirmation before opening saved entries, hardened SQLite connection handling, and redacted update-source logging.
- Stay updated through Velopack-powered GitHub Releases for installed desktop builds. Every update package must pass Custodian's signature policy before the updater uses it.
| Scan overview | Treemap distribution |
|---|---|
![]() |
![]() |
| Scan in progress | Folder drilldown |
|---|---|
![]() |
![]() |
The desktop app keeps targets, scan navigation, sortable detail rows, summary metrics, and charts visible in one workspace so repeated cleanup passes do not require jumping between windows.
- Opening a file that isn't a Custodian scan, or a scan file with missing or invalid values, now fails with a message that says what is wrong, instead of a generic error or wrong sizes.
- Faster scans. MFT scans read the
$MFTdirectly from the volume, recursive scans work through several folders at once, and the desktop app shows results without first building the whole folder tree. - The Folder Map lists every drive and folder scanned in the session, so any of them is one click away.
- View > Always open as administrator no longer breaks installs and updates (error 740). Custodian now asks for elevation itself as it starts.
- Saved scans are checked before use, and the terminal UI treats opened scans as review-only, as the desktop app already did.
- Every update package must pass Custodian's signature policy before the updater uses it.
If you use Always open as administrator on an older version, update from
inside Custodian (Help > Check for Updates), or turn the setting off before you
run a new Setup.exe.
Custodian is built for local and locked-down environments. Scans run on the machine where the app is launched; Custodian does not upload file metadata to a cloud service. Cloud-provider support discovers local OneDrive, Nextcloud, and Dropbox sync roots from desktop-client metadata and scans them as local folders; it does not authenticate to those services, call cloud APIs, upload data, or intentionally download online-only placeholders. Android / MTP support is read-only for phone storage, and copy operations write only to the PC destination you choose. Opening entries from a saved scan prompts before touching network or remote paths, because saved scan files can come from untrusted sources. Saved scan files are checked before use, and a scan opened from a file is review-only in both the desktop app and the TUI: Custodian won't copy, move, recycle, or delete files from it.
Get the latest release from:
https://github.com/C-Tech-Solutions/custodian/releases/latest
Release assets include:
Custodian.DiskAnalyzer-win-Setup.exe- installed desktop app with updates.Custodian.DiskAnalyzer-win-Portable.zip- portable desktop app, TUI, and CLI.Custodian.DiskAnalyzer-<version>-full.nupkg,RELEASES, andreleases.win.json- Velopack update assets for installed clients.Custodian-<version>.spdx.jsonandSHA256SUMS.txt- release provenance and integrity metadata.
- Windows 10, Windows 11, or Windows Server with Desktop Experience for the WPF desktop app.
- Administrator launch is recommended for full local NTFS MFT access.
- Android phone scanning requires the desktop app, an unlocked phone, and USB File Transfer mode. Custodian can analyze phone metadata, open selected phone folders or files in Explorer when Windows supports it, and copy selected files to the PC, but it does not delete, rename, move, or modify files on the phone. Allocated-size/MFT data is not available.
- The TUI and CLI can run in more constrained server workflows, including terminal sessions, scheduled jobs, recursive scans, and export tasks.
- Choose a drive, folder, OneDrive sync root, UNC path, or connected phone storage root.
- Pick Auto, Recursive, or MFT scanning.
- Scan and inspect space by folder, file, extension, or chart slice.
- Switch to another drive and return to any cached scan without rescanning.
- Save the scan for later, export CSV/JSON, or manage deleted items through the Recycle Bin view.
Custodian warns when it is not running as administrator and can relaunch itself elevated when you need MFT scanning to reach protected NTFS metadata. Use View > Always open as administrator when you want every launch to request elevation. Custodian asks for it as it starts, before any window opens; if you decline the prompt it opens without administrator rights and shows the warning banner. Installer and update steps never ask for elevation, so the installer and in-app updates work with the setting on.
Drive targets show whether a scan is currently running or already cached for the session. Uncached drives show a Start Scan prompt instead of clearing the workspace without direction.
The Folder Map on the left lists every drive and folder scanned in the session, in path order, and stays in place while another target scans. Clicking a folder under another scan switches to that scan and opens the folder. The map fits the panel width and resizes with it.
OneDrive, Nextcloud, and Dropbox roots appear under Targets when local desktop client metadata exposes a sync folder. OneDrive includes common personal/business account roots and Known Folder Move folders under that root. The desktop Targets pane includes a Cloud toggle for hiding or showing cloud-provider rows and mounted cloud drives without changing manual path scans. Cloud-provider targets use the recursive scanner even when Auto or MFT is selected, and saved scans/exports carry provider metadata so the source remains clear later.
Connected Android phones appear under Targets when Windows exposes readable MTP storage. If a phone is locked or left in charging-only mode, Custodian shows a target hint asking you to unlock the phone and choose File Transfer mode. Phone scan rows can be opened in Explorer at the storage-root level or copied to a PC folder; selected folders copy recursively and existing PC files are left untouched by auto-renaming duplicates.
custodian scan C:\Data --out data.custodian-scan
custodian scan \\server\share --export share.csv --silent
custodian export data.custodian-scan --format json --out data.json
custodian scan E:\Archive --mode recursive --threads 2
custodian scan C:\ --mode mft --mft-read enumThe recursive engine lists up to eight folders at once (fewer on machines with
fewer processors). --threads <n> sets that number, for example --threads 1
or 2 for a spinning disk. Cloud-provider folders are always scanned on one
thread.
MFT scans read the $MFT straight from the volume device: one sequential,
read-only pass over the $MFT's own clusters, then small reads of the attribute
lists stored outside it for the few files whose name depends on them, with the
volume opened read-only and shared. Nothing is written. Endpoint-protection products can flag raw
volume reads, because credential-theft tools use them too. If the direct read
cannot run, the scan falls back to FSCTL_ENUM_USN_DATA on its own and says why
in its diagnostics. --mft-read enum uses that path only.
.\tui\Custodian.Tui.exe
.\tui\Custodian.Tui.exe --scan C:\Data --mode auto
.\tui\Custodian.Tui.exe --open data.custodian-scanThe TUI provides keyboard/mouse terminal navigation for scans, saved scan files, terminal-native charts, Recycle Bin review, Android / MTP scan and copy actions, CSV/JSON export, update checks, and elevation settings. It shares the same local scan and safety behavior as the desktop app.
dotnet restore
dotnet build
dotnet test
.\scripts\publish-portable.ps1The portable output is written to artifacts\portable\Custodian.
The primary installer and update channel are built with Velopack:
.\scripts\publish-velopack.ps1 -Version 1.5.8Release assets are written under artifacts\velopack. Publish those assets to
GitHub Releases so installed apps can discover updates:
$env:GH_TOKEN = "<token with release access>"
.\scripts\upload-velopack-github.ps1 -Version 1.5.8 -ExpectedCommit <40-character-SHA>The repo pins vpk 0.0.626 because newer tool builds require a .NET runtime
that may not be installed in the current development environment.
Custodian release scripts can sign Windows artifacts with Azure Artifact Signing (formerly Azure Trusted Signing). Install Microsoft's client tools on the build machine first:
winget install -e --id Microsoft.Azure.ArtifactSigningClientToolsThen authenticate with Azure. For local signing, az login is enough when the
Azure CLI is installed and the signed-in identity has the certificate-profile
signer role. The protected GitHub release workflow uses federated OIDC and does
not store an Azure client secret.
Provide the signing profile with either a metadata file:
$env:CUSTODIAN_AZURE_SIGNING_METADATA = "C:\secure\custodian-signing.json"or environment variables:
$env:CUSTODIAN_AZURE_SIGNING_ENDPOINT = "https://eus.codesigning.azure.net"
$env:CUSTODIAN_AZURE_SIGNING_ACCOUNT = "<artifact-signing-account>"
$env:CUSTODIAN_AZURE_SIGNING_PROFILE = "<certificate-profile>"Build signed Velopack release assets with:
.\scripts\publish-velopack.ps1 -Version 1.5.8 -SignThe -Sign switch uses scripts\sign-azure-artifact.ps1 through Velopack's
signing template so the packaged PE files and generated installer are signed and
verified. The portable package can be signed before zipping with:
.\scripts\publish-portable.ps1 -SignIf SignTool or Azure.CodeSigning.Dlib.dll are installed in a nonstandard
location, set CUSTODIAN_SIGNTOOL_PATH and
CUSTODIAN_AZURE_SIGNING_DLIB_PATH, or pass -SignToolPath and
-AzureSigningDlibPath.
See CHANGELOG.md for release notes.
Custodian follows the update channel embedded in the installed Velopack package.
The scripts default to the win channel; pass -Channel <name> when producing
or uploading another channel.
Installed apps check for updates on startup by default. Use Help > Automatically download updates on startup to turn the launch-time check/download on or off; Custodian still asks before restarting to install a downloaded update.
Optional environment overrides:
CUSTODIAN_UPDATE_CHANNEL- deliberate local or managed channel override.CUSTODIAN_GITHUB_TOKEN- token for authenticated GitHub release checks in managed deployments.CUSTODIAN_UPDATE_PRERELEASES- set to0or1to override prerelease checks for non-stable channels.CUSTODIAN_UPDATE_SOURCE- local release folder for unsigned update testing.
For local update validation without GitHub Releases, run
scripts\prepare-local-update-test.ps1, install the preserved baseline setup,
set CUSTODIAN_UPDATE_SOURCE to the generated local release folder, and launch
the installed test build.
The Inno Setup script at installer\Custodian.iss packages the portable publish
output and creates Start Menu shortcuts for the GUI, TUI, and CLI. This path
remains available for manual or legacy installs, but it is not the auto-update
channel.
After compiling the Inno installer, sign it with:
.\scripts\sign-azure-artifact.ps1 -Path .\artifacts\installer\CustodianSetup.exeCustodian is released under the MIT License.
Copyright (c) 2026 C-Tech Solutions LLC.



