noxdir

NoxDir

NoxDir is a high-performance, cross-platform command-line tool for visualizing and exploring your file system usage. It detects mounted drives or volumes and presents disk usage metrics through a responsive, keyboard-driven terminal UI. Designed to help you quickly locate space hogs and streamline your cleanup workflow. Supports: Windows, macOS, and Linux.

https://github.com/user-attachments/assets/f85c6dc8-96b6-472e-bd88-fd5fbd04e81a

Installation

MacOS

Homebrew

Stable release:

brew tap crumbyte/noxdir
brew install --cask noxdir

Nightly release:

brew tap crumbyte/noxdir
brew uninstall --cask noxdir # If the stable version was installed previously
brew install --cask noxdir-nightly

Linux

Arch-based Linux distros

pacman -S noxdir

NixOS / Nix

NoxDir can be installed either directly from nixpkgs or used via flake:

From nixpkgs (unstable channel):

nix-env -iA nixpkgs.noxdir

Or in your configuration.nix:

environment.systemPackages = with pkgs; [
  noxdir
];

Using flake:

nix run github:crumbyte/noxdir

Or add to your flake.nix:

{
  inputs.noxdir.url = "github:crumbyte/noxdir";
}

Other Linux distros

curl -s https://crumbyte.github.io/noxdir/scripts/install.sh | bash

curl -s https://crumbyte.github.io/noxdir/scripts/install.sh | bash -s -- v1.2.0

Windows

Scoop

Stable release:

scoop bucket add crumbyte https://github.com/crumbyte/scoop-bucket
scoop install noxdir

Nightly release:

scoop bucket add crumbyte https://github.com/crumbyte/scoop-bucket
scoop uninstall noxdir # If the stable version was installed previously
scoop install noxdir-nightly

Pre-compiled binaries

Obtain the latest optimized binary from the Releases page. The application is self-contained and requires no installation process.

Install Go package (Go 1.26)

go install github.com/crumbyte/noxdir@latest

Build from source (Go 1.26)

git clone https://github.com/crumbyte/noxdir.git
cd noxdir
make build

./bin/noxdir

Usage

Just run in the terminal:

noxdir

The interactive interface initializes immediately without configuration requirements.

Flags

NoxDir accepts flags on a startup. Here's a list of currently available CLI flags:

…

Configuration File

On first launch, the application automatically generates a simple configuration file. This file allows you to define default behaviors without needing to pass flags every time.

The configuration file is created at:

• Windows: %LOCALAPPDATA%\.noxdir\settings.json (e.g., C:\Users\{user}\AppData\Local\.noxdir\settings.json)
• Linux/macOS: ~/.noxdir/settings.json

The created configurations file already contains all available settings. Values follow the same format and behavior as CLI flags. For example:

{
  "exclude": "node_modules,Steam\\appcache",
  "colorSchema": "custom_schema.json",
  "noEmptyDirs": true,
  "noHidden": false,
  "simpleColor": true,
  "useCache": false
}

To quickly the configuration file you can open it right from the application using % key binding.

️ Caching for Faster Scanning

Scanning can take time, especially on volumes with many small files and directories (e.g., log folders or node_modules). To improve performance in such cases, NoxDir supports caching.

When the --use-cache (-c) flag is provided, NoxDir will attempt to use an existing cache file for the selected drive or volume. If no cache file exists, it performs a full scan and saves the result to a cache file for future use.

If a cache file is found, the full scan is skipped by default (unless you explicitly want to see the structure delta). Scanning is then performed on demand using the r (refresh) key, which updates the cache after the session ends.

Cache file locations:

• Windows: %LOCALAPPDATA%\.noxdir\cache (e.g., C:\Users\{user}\AppData\Local\.noxdir\cache)
• Linux/macOS: ~/.noxdir/cache

To clear all cached data, use the --clear-cache flag.

Viewing Changes (Delta Mode)

NoxDir can display file system changes since your last session. It highlights added or deleted files and directories, as well as changes in disk space usage. The diff is calculated by comparing the current directory state against its cached version. If no cache exists from the previous session, no differences will be shown.

To view changes in the current directory, press the + key (toggle diff). NoxDir will compare the current state of the directory with its cached version and display the difference:

⌨️ Key Bindings

NoxDir provides full support for custom key bindings, allowing users to override nearly all interactive controls. Bindings are defined in the configuration file. By default, all key binding fields are set to null. When a field is null or omitted, the default binding is used.

Default bindings are defined as follows:

{
  "driveBindings": {
    "levelDown":    ["enter", "right"],
  },
  "dirBindings": {
    "levelUp":    ["backspace", "left"],
    "levelDown":  ["enter", "right"],
    "delete":     ["!"],
    "topFiles":   ["ctrl+q"],
    "topDirs":    ["ctrl+e"],
    "filesOnly":  [","],
    "dirsOnly":   ["."],
    "nameFilter": ["ctrl+f"],
    "chart":      ["ctrl+w"],
    "diff":       ["+"]
  },
  "explore": ["e"],
  "quit":    ["q", "ctrl+c"],
  "refresh": ["r"],
  "help":    ["?"],
  "config":  ["%"]
}

Each entry maps an action name to one or more key sequences. Bindings support modifiers such as ctrl, alt, and shift, and are case-sensitive.

Notes

• Multiple bindings per action are supported.
• If a binding is explicitly set to null, the default will be used.
• Removing a binding entry is equivalent to setting it to null.
• Bindings must be declared as arrays of strings, even for single-key bindings.

Custom config example:

{
  "dirBindings": {
    "topFiles": ["t"],
    "topDirs": ["T"]
  }
}

Colors Customization

NoxDir supports color schema customization via the --color-schema flag. You can provide a JSON configuration to adjust colors, borders, glyph rendering, and more.

A full example schema (including all default settings) is available here. You can also provide a partial config that overrides only specific values.

Example:

{
  "statusBarBorder": false,
  "usageProgressBar": {
    "fullChar": "█",
    "emptyChar": "░"
  }
}

In this example, the status bar border is disabled, and the usage progress bar is rendered using ANSI characters (█, ░) instead of emojis (, ).

FAQ

• Q: Can I use this in scripts or headless environments?

• A: Not yet — it's designed for interactive use.

• Q: What are the security implications of running NoxDir?

• A: NoxDir operates in a strictly read-only capacity, with no file modification capabilities except for deletion, which requires confirmation.

• Q: The interface appears to have rendering issues with icons or formatting, and there are no multiple panes like in the screenshots.

• A: Visual presentation depends on terminal capabilities and font configuration. For optimal experience, a terminal with Unicode and glyph support is recommended. The screenshots were made in WezTerm using MesloLGM Nerd Font font. If your font does not support glyphs consider using --siimple-color flag.

• Q: The scanning process is too slow.

• A: Consider using caching, exclusion, or running the application only for specific directories. The caching can be enabled with the flag -c, --use-cache or in the configuration file. With caching enabled, you choose which directories must be re-scanned with the r key. Exclusion flag -x, --exclude allows providing a list of directories that must be skipped during scanning, e.g., .node_modules. Also, predefined root -r, --root will start the application from the specified directory instead of scanning the entire file system.