- Notifications
You must be signed in to change notification settings - Fork13
Terminal utility for visualizing file system usage.
License
crumbyte/noxdir
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
NoxDir is a high-performance, cross-platform command-line tool forvisualizing and exploring your file system usage. It detects mounted drives orvolumes and presents disk usage metrics through a responsive, keyboard-driventerminal UI. Designed to help you quickly locate space hogs and streamline yourcleanup workflow. Supports:Windows,macOS, andLinux.
Stable release:
brew tap crumbyte/noxdirbrew install --cask noxdir
Nightly release:
brew tap crumbyte/noxdirbrew uninstall --cask noxdir# If the stable version was installed previouslybrew install --cask noxdir-nightlypacman -S noxdir
curl -s https://crumbyte.github.io/noxdir/scripts/install.sh| bashcurl -s https://crumbyte.github.io/noxdir/scripts/install.sh| bash -s -- v0.6.0Obtain the latest optimized binary fromtheReleases page. Theapplication is self-contained and requires no installation process.
go install github.com/crumbyte/noxdir@latest
git clone https://github.com/crumbyte/noxdir.gitcd noxdirmake build./bin/noxdirJust run in the terminal:
noxdir
The interactive interface initializes immediately without configurationrequirements.
NoxDir accepts flags on a startup. Here's a list of currently availableCLI flags:
Usage: noxdir [flags]Flags: --clear-cache Delete all cache files from the application's directory. Example: --clear-cache (provide a flag) --color-schema string Set the color schema configuration file. The file contains a custom color settings for the UI elements. -x, --exclude strings Exclude specific directories from scanning. Useful for directories with many subdirectories but minimal disk usage (e.g., node_modules). NOTE: The check targets any string occurrence. The excluded directory name can be either an absolute path or only part of it. In the last case, all directories whose name contains that string will be excluded from scanning. Example: --exclude="node_modules,Steam\appcache" (first rule will exclude all existing "node_modules" directories) -h, --help help for noxdir -d, --no-empty-dirs Excludes all empty directories from the output. The directory is considered empty if it or its subdirectories do not contain any files. Even if the specific directory represents the entire tree structure of subdirectories, without a single file, it will be completely skipped. Default value is "false". Example: --no-empty-dirs (provide a flag) --no-hidden Excludes all hidden files and directories from the output. The entry is considered hidden if its name starts with a dot, e.g., ".git". Default value is "false". Example: --no-hidden (provide a flag) -r, --root string Start from a predefined root directory. Instead of selecting the target drive and scanning all folders within, a root directory can be provided. In this case, the scanning will be performed exclusively for the specified directory, drastically reducing the scanning time. Providing an invalid path results in a blank application output. In this case, a "backspace" still can be used to return to the drives list. Also, all trailing slash characters will be removed from the provided path. Example: --root="C:\Program Files (x86)" --simple-color Use a simplified color schema without emojis and glyphs. Example: --simple-color (provide a flag) -l, --size-limit string Define size limits/boundaries for files that should be shown in the scanner output. Files that do not fit in the provided limits will be skipped. The size limits can be defined using format "<size><unit>:<size><unit> where "unit" value can be: KB, MB, GB, TB, PB, and "size" is a positive numeric value. For example: "1GB:5GB". Both values are optional. Therefore, it can also be an upper bound only or a lower bound only. These are the valid flag values: "1GB:", ":10GB" NOTE: providing this flag will lead to inaccurate sizes of the directories, since the calculation process will include only files that meet the boundaries. Also, this flag cannot be applied to the directories but only to files within. Example: --size-limit="3GB:20GB" --size-limit="3MB:" --size-limit=":1TB" -c, --use-cache Force the application to cache the data. With cache enabled, the full file system scan will be performed only once. After that, the cache will be used as long as the flag is provided. The cache will always store the last session data. In order to update the cache and the application's state, use the "r" (refresh) command on a target directory. Default value is "false". Example: -c|--use-cache (provide a flag) -v, --version Print the application version and exit.It identifies all available partitions for Windows, or volumes in the case ofmacOS and Linux. It'll immediately show the capacity info for all drives,including file system type, total capacity, free space, and usage data. Alldrives will be sorted (by default) by the free space left.
PressEnter to explore a particular drive and check what files or directoriesoccupy the most space. Wait while the scan is finished, and the status willupdate in the status bar.Now you have the full view of the files and directories, including the spaceusage info by each entry. Usectrl+qto immediately see the biggest files on the drive, orctrl+e tosee the biggest directories. Usectrl+f to filter entries by their names or, and. to show only files or directories.
NoxDir can display file system changes since your last session. It highlights added or deleted files and directories, aswell as changes in disk space usage.
To view changes in the current directory, press the+ key (toggle diff). NoxDir will compare the current state of thedirectory with its cached version and display the difference:
The diff is calculated by comparing the current directory state against its cached version. If no cache exists from theprevious session, no differences will be shown.
On first launch, the application automatically generates a simple configuration file. This file allows you to definedefault 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 and has the following structure:
{"colorSchema":"","exclude":null,"noEmptyDirs":false,"noHidden":false,"simpleColor":false,"useCache":false,"bindings": {"driveBindings": {"levelDown": [] },"dirBindings": {"levelUp":null,"levelDown":null,"delete":null,"topFiles":null,"topDirs":null,"filesOnly":null,"dirsOnly":null,"nameFilter":null,"chart":null,"diff":null },"explore":null,"quit":null,"refresh":null,"help":null,"diff":null,"config":null }}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}👉 If you cannot find the configuration file you can open it right from the application using% key binding.
Scanning can take time, especially on volumes with many small files and directories (e.g., log folders ornode_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 driveor 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 performedon demand using ther (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.
NoxDir provides a set of commands you can run on one or multiple selected entries.
- Open the command bar. Press the
:key inside NoxDir to bring up the command bar. - Explore available commands. Type:
helpto list all currently available commands. For details on a specific command,use the-hflag. Example:pack -h. - Run a command. Select the entries you want, then type a command in the command bar. In the example below, fourselected items are packed into an archive named
archivewith no compression:pack -o archive - Press
escto close the command bar.
NoxDir provides full support for custom key bindings, allowing users to override nearly all interactive controls.Bindings are defined in theconfiguration file. By default, all key binding fields are set tonull. When a field isnull 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 asctrl,alt, andshift, 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"] }}NoxDir supports color schema customization via the--color-schema flag. You can provide a JSON configuration to adjustcolors, borders, glyph rendering, and more.
A full example schema (including all default settings) isavailablehere. You can also provide a partialconfig thatoverrides 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 (🟥, 🟩).
- The scan process on macOS might be slow sometimes. If it is an issue, considerusing
--excludeargument.
- Real-time filesystem event monitoring and interface updates
- Exportable reports in various formats (JSON, CSV, HTML)
- 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 filemodification capabilities except for deletion, which requires confirmation.
- Q: The interface appears to have rendering issues with icons orformatting, and there are no multiple panes like in the screenshots.
- A: Visual presentation depends on terminal capabilities and fontconfiguration. For optimal experience, a terminal with Unicode and glyphsupport is recommended. The screenshots were made in
WezTermusingMesloLGM Nerd Fontfont.
Pull requests are welcome! If you’d like to add features or report bugs, pleaseopen an issue first to discuss.
MIT ©crumbyte
About
Terminal utility for visualizing file system usage.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors5
Uh oh!
There was an error while loading.Please reload this page.