{"id":35451653,"url":"https://github.com/crumbyte/noxdir","last_synced_at":"2026-02-06T04:04:27.567Z","repository":{"id":292586676,"uuid":"976807556","full_name":"crumbyte/noxdir","owner":"crumbyte","description":"Terminal utility for visualizing file system usage.","archived":false,"fork":false,"pushed_at":"2026-01-18T21:29:29.000Z","size":51585,"stargazers_count":362,"open_issues_count":1,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-19T06:21:33.003Z","etag":null,"topics":["cross-platform","disk-space-analyzer","disk-usage","file-explorer","storage-virtualization","terminal-ui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crumbyte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-02T19:37:10.000Z","updated_at":"2026-01-18T21:29:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"ddae8dac-ff06-49de-87d3-da76fa5b315e","html_url":"https://github.com/crumbyte/noxdir","commit_stats":null,"previous_names":["crumbyte/noxdir"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/crumbyte/noxdir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crumbyte%2Fnoxdir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crumbyte%2Fnoxdir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crumbyte%2Fnoxdir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crumbyte%2Fnoxdir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crumbyte","download_url":"https://codeload.github.com/crumbyte/noxdir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crumbyte%2Fnoxdir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29149628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","disk-space-analyzer","disk-usage","file-explorer","storage-virtualization","terminal-ui"],"created_at":"2026-01-03T03:23:22.811Z","updated_at":"2026-02-06T04:04:27.562Z","avatar_url":"https://github.com/crumbyte.png","language":"Go","readme":"# 🧹 NoxDir\n\n[![Build](https://github.com/crumbyte/noxdir/actions/workflows/build.yml/badge.svg)](https://github.com/crumbyte/noxdir/actions/workflows/build.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/crumbyte/noxdir)](https://goreportcard.com/report/github.com/crumbyte/noxdir)\n![GitHub Release](https://img.shields.io/github/v/release/crumbyte/noxdir)\n\n**NoxDir** is a high-performance, cross-platform command-line tool for\nvisualizing and exploring your file system usage. It detects mounted drives or\nvolumes and presents disk usage metrics through a responsive, keyboard-driven\nterminal UI. Designed to help you quickly locate space hogs and streamline your\ncleanup workflow. Supports: **Windows**, **macOS**, and **Linux**.\n\n[//]: # (![full-preview!]\u0026#40;/img/full-preview.png \"full preview\"\u0026#41;)\n\n[//]: # ()\n[//]: # (![two panes!]\u0026#40;/img/two-panes.png \"two panes\"\u0026#41;)\n\n![full-preview!](/img/preview.png \"full preview\")\n![full-preview!](/img/linux-preview.png \"full preview\")\n![full-preview!](/img/win-cmd.png \"full preview\")\n\n## 📦 Installation\n\n### 🍺 Homebrew\n\nStable release:\n\n```bash\nbrew tap crumbyte/noxdir\nbrew install --cask noxdir\n```\n\nNightly release:\n\n```bash\nbrew tap crumbyte/noxdir\nbrew uninstall --cask noxdir # If the stable version was installed previously\nbrew install --cask noxdir-nightly\n```\n\n### Arch based Linux distros\n\n```bash\npacman -S noxdir\n```\n\n### NixOS / Nix\n\nNoxDir can be installed either directly from nixpkgs or used via flake:\n\n**From nixpkgs (unstable channel):**\n\n```bash\nnix-env -iA nixpkgs.noxdir\n```\n\nOr in your `configuration.nix`:\n\n```nix\nenvironment.systemPackages = with pkgs; [\n  noxdir\n];\n```\n\n**Using flake:**\n\n```bash\nnix run github:crumbyte/noxdir\n```\n\nOr add to your `flake.nix`:\n\n```nix\n{\n  inputs.noxdir.url = \"github:crumbyte/noxdir\";\n}\n```\n\n### Other Linux distros\n\n```bash\ncurl -s https://crumbyte.github.io/noxdir/scripts/install.sh | bash\n```\n\n```bash\ncurl -s https://crumbyte.github.io/noxdir/scripts/install.sh | bash -s -- v0.6.0\n```\n\n### Pre-compiled Binaries\n\nObtain the latest optimized binary from\nthe [Releases](https://github.com/crumbyte/noxdir/releases) page. The\napplication is self-contained and requires no installation process.\n\n### Go install (Go 1.24+)\n\n```bash\ngo install github.com/crumbyte/noxdir@latest\n```\n\n### Build from source (Go 1.24+)\n\n```bash\ngit clone https://github.com/crumbyte/noxdir.git\ncd noxdir\nmake build\n\n./bin/noxdir\n```\n\n## 🛠 Usage\n\nJust run in the terminal:\n\n```bash\nnoxdir\n```\n\nThe interactive interface initializes immediately without configuration\nrequirements.\n\n## 🚩 Flags\n\nNoxDir accepts flags on a startup. Here's a list of currently available\nCLI flags:\n\n```\nUsage:\n  noxdir [flags]\n\nFlags:\n      --clear-cache           Delete all cache files from the application's directory.\n\n                              Example: --clear-cache (provide a flag)\n\n      --color-schema string   Set the color schema configuration file. The file contains a custom\n                              color settings for the UI elements.\n\n  -x, --exclude strings       Exclude specific directories from scanning. Useful for directories\n                              with many subdirectories but minimal disk usage (e.g., node_modules).\n\n                              NOTE: The check targets any string occurrence. The excluded directory\n                              name can be either an absolute path or only part of it. In the last case,\n                              all directories whose name contains that string will be excluded from\n                              scanning.\n\n                              Example: --exclude=\"node_modules,Steam\\appcache\"\n                              (first rule will exclude all existing \"node_modules\" directories)\n  -h, --help                  help for noxdir\n  -d, --no-empty-dirs         Excludes all empty directories from the output. The directory is\n                              considered empty if it or its subdirectories do not contain any files.\n\n                              Even if the specific directory represents the entire tree structure of\n                              subdirectories, without a single file, it will be completely skipped.\n\n                              Default value is \"false\".\n\n                              Example: --no-empty-dirs (provide a flag)\n\n      --no-hidden             Excludes all hidden files and directories from the output. The entry is\n                              considered hidden if its name starts with a dot, e.g., \".git\".\n\n                              Default value is \"false\".\n\n                              Example: --no-hidden (provide a flag)\n\n  -r, --root string           Start from a predefined root directory. Instead of selecting the target\n                              drive and scanning all folders within, a root directory can be provided.\n                              In this case, the scanning will be performed exclusively for the specified\n                              directory, drastically reducing the scanning time.\n\n                              Providing an invalid path results in a blank application output. In this\n                              case, a \"backspace\" still can be used to return to the drives list.\n                              Also, all trailing slash characters will be removed from the provided\n                              path.\n\n                              Example: --root=\"C:\\Program Files (x86)\"\n      --simple-color          Use a simplified color schema without emojis and glyphs.\n\n                              Example: --simple-color (provide a flag)\n\n  -l, --size-limit string     Define size limits/boundaries for files that should be shown in the\n                              scanner output. Files that do not fit in the provided limits will be\n                              skipped.\n\n                              The size limits can be defined using format \"\u003csize\u003e\u003cunit\u003e:\u003csize\u003e\u003cunit\u003e\n                              where \"unit\" value can be: KB, MB, GB, TB, PB, and \"size\" is a positive\n                              numeric value. For example: \"1GB:5GB\".\n\n                              Both values are optional. Therefore, it can also be an upper bound only\n                              or a lower bound only. These are the valid flag values: \"1GB:\", \":10GB\"\n\n                              NOTE: providing this flag will lead to inaccurate sizes of the\n                              directories, since the calculation process will include only files\n                              that meet the boundaries. Also, this flag cannot be applied to the\n                              directories but only to files within.\n\n                              Example:\n                                --size-limit=\"3GB:20GB\"\n                                --size-limit=\"3MB:\"\n                                --size-limit=\":1TB\"\n\n  -c, --use-cache             Force the application to cache the data. With cache enabled, the full\n                              file system scan will be performed only once. After that, the cache will be\n                              used as long as the flag is provided.\n\n                              The cache will always store the last session data. In order to update the\n                              cache and the application's state, use the \"r\" (refresh) command on a\n                              target directory.\n\n                              Default value is \"false\".\n\n                              Example: -c|--use-cache (provide a flag)\n\n  -v, --version              Print the application version and exit.\n```\n\n## 🔧 Configuration File\n\nOn first launch, the application automatically generates a simple configuration file. This file allows you to define\ndefault behaviors without needing to pass flags every time.\n\nThe configuration file is created at:\n\n* Windows: `%LOCALAPPDATA%\\.noxdir\\settings.json` (e.g., `C:\\Users\\{user}\\AppData\\Local\\.noxdir\\settings.json`)\n* Linux/macOS: `~/.noxdir/settings.json`\n\nThe created configurations file already contains all available settings and has the following structure:\n\n```json\n{\n  \"colorSchema\": \"\",\n  \"exclude\": null,\n  \"noEmptyDirs\": false,\n  \"noHidden\": false,\n  \"simpleColor\": false,\n  \"useCache\": false,\n  \"bindings\": {\n    \"driveBindings\": {\n      \"levelDown\": []\n    },\n    \"dirBindings\": {\n      \"levelUp\": null,\n      \"levelDown\": null,\n      \"delete\": null,\n      \"topFiles\": null,\n      \"topDirs\": null,\n      \"filesOnly\": null,\n      \"dirsOnly\": null,\n      \"nameFilter\": null,\n      \"chart\": null,\n      \"diff\": null,\n      \"toggleSelectAll\": null,\n      \"toggleSelection\": null\n    },\n    \"explore\": null,\n    \"quit\": null,\n    \"refresh\": null,\n    \"help\": null,\n    \"diff\": null,\n    \"config\": null\n  }\n}\n```\n\nValues follow the same format and behavior as CLI flags. For example:\n\n```json\n{\n  \"exclude\": \"node_modules,Steam\\\\appcache\",\n  \"colorSchema\": \"custom_schema.json\",\n  \"noEmptyDirs\": true,\n  \"noHidden\": false,\n  \"simpleColor\": true,\n  \"useCache\": false\n}\n```\n\n👉 If you cannot find the configuration file you can open it right from the application using `%` key binding.\n\n## 🗂️ Caching for Faster Scanning\n\nScanning can take time, especially on volumes with many small files and directories (e.g., log folders or\n`node_modules`). To improve performance in such cases, NoxDir supports caching.\n\nWhen the `--use-cache (-c)` flag is provided, NoxDir will attempt to use an existing cache file for the selected drive\nor volume. If no cache file exists, it performs a full scan and saves the result to a cache file for future use.\n\nIf a cache file is found, the full scan is skipped by default (unless you explicitly want to see the structure delta).\nScanning is then performed **on demand** using the `r` (refresh) key, which updates the cache after the session ends.\n\nCache file locations:\n\n* Windows: `%LOCALAPPDATA%\\.noxdir\\cache` (e.g., `C:\\Users\\{user}\\AppData\\Local\\.noxdir\\cache`)\n* Linux/macOS: `~/.noxdir/cache`\n\nTo clear all cached data, use the `--clear-cache` flag.\n\n## 🔍 Viewing Changes (Delta Mode)\n\nNoxDir can display file system changes since your last session. It highlights added or deleted files and directories, as\nwell 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\nprevious session, no differences will be shown.\n\nTo view changes in the current directory, press the `+` key (toggle diff). NoxDir will compare the current state of the\ndirectory with its cached version and display the difference:\n\n![diff!](/img/diff.png \"diff\")\n\n## ⌨️ Key Bindings\n\nNoxDir provides full support for custom key bindings, allowing users to override nearly all interactive controls.\nBindings are defined in the [configuration file](#-configuration-file). By default, all key binding fields are set to\n`null`. When a field is `null` or omitted, the default binding is used.\n\nDefault bindings are defined as follows:\n\n```json\n{\n  \"driveBindings\": {\n    \"levelDown\":    [\"enter\", \"right\"],\n  },\n  \"dirBindings\": {\n    \"levelUp\":    [\"backspace\", \"left\"],\n    \"levelDown\":  [\"enter\", \"right\"],\n    \"delete\":     [\"!\"],\n    \"topFiles\":   [\"ctrl+q\"],\n    \"topDirs\":    [\"ctrl+e\"],\n    \"filesOnly\":  [\",\"],\n    \"dirsOnly\":   [\".\"],\n    \"nameFilter\": [\"ctrl+f\"],\n    \"chart\":      [\"ctrl+w\"],\n    \"diff\":       [\"+\"]\n  },\n  \"explore\": [\"e\"],\n  \"quit\":    [\"q\", \"ctrl+c\"],\n  \"refresh\": [\"r\"],\n  \"help\":    [\"?\"],\n  \"config\":  [\"%\"]\n}\n```\n\nEach entry maps an action name to one or more key sequences. Bindings support modifiers such as `ctrl`, `alt`, and\n`shift`, and are case-sensitive.\n\n**Notes**\n\n- Multiple bindings per action are supported.\n- If a binding is explicitly set to `null`, the default will be used.\n- Removing a binding entry is equivalent to setting it to `null`.\n- Bindings must be declared as arrays of strings, even for single-key bindings.\n\nCustom config example:\n\n```json\n{\n  \"dirBindings\": {\n    \"topFiles\": [\"t\"],\n    \"topDirs\": [\"T\"]\n  }\n}\n```\n\n## 🎨 Colors Customization\n\nNoxDir supports color schema customization via the `--color-schema` flag. You can provide a JSON configuration to adjust\ncolors, borders, glyph rendering, and more.\n\nA full example schema (including all default settings) is\navailable [here](https://github.com/crumbyte/noxdir/blob/main/default-color-schema.json). You can also provide a partial\nconfig that\noverrides only specific values.\n\nExample:\n\n```json\n{\n  \"statusBarBorder\": false,\n  \"usageProgressBar\": {\n    \"fullChar\": \"█\",\n    \"emptyChar\": \"░\"\n  }\n}\n```\n\nIn this example, the status bar border is disabled, and the usage progress bar is rendered using ANSI characters (█, ░)\ninstead of emojis (🟥, 🟩).\n\n## 🙋 FAQ\n- **Q:** Can I use this in scripts or headless environments?\n- **A:** Not yet — it's designed for interactive use.\n  \u003cbr\u003e\u003cbr\u003e\n- **Q:** What are the security implications of running NoxDir?\n- **A:** NoxDir operates in a strictly read-only capacity, with no file\n  modification capabilities except for deletion, which requires confirmation.\n  \u003cbr\u003e\u003cbr\u003e\n- **Q:** The interface appears to have rendering issues with icons or\n  formatting, and there are no multiple panes like in the screenshots.\n- **A:** Visual presentation depends on terminal capabilities and font\n  configuration. For optimal experience, a terminal with Unicode and glyph\n  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.\n  \u003cbr\u003e\u003cbr\u003e\n- **Q:** The scanning process is too slow.\n- **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.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrumbyte%2Fnoxdir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrumbyte%2Fnoxdir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrumbyte%2Fnoxdir/lists"}