Parallel disk usage analyzer for macOS and Linux. Scans directories with multi-threaded I/O, categorizes files (temp, cache, build artifacts), and presents results as rich CLI tables or an interactive TUI with vim-style navigation.

100% AI-written. The vast majority of this codebase was written by Claude (Anthropic), with contributions from Codex (OpenAI). Human involvement was limited to directing, reviewing, and benchmarking.

CLI summary (uv run dux -n)

TUI overview (uv run dux)

TUI browse — expandable directory tree with disk usage bars

• Parallel scanning with configurable thread pool (default 4 workers)
• Interactive TUI with 5 views, vim keybindings, localized subtree refresh, search/filter, and pagination
• Composable CLI flags — --top-temp, --top-cache, --top-dirs, --top-files each print their own table and can be freely combined
• 59 built-in pattern rules for detecting temp files, caches, and build artifacts across dozens of ecosystems (Node, Python, Rust, Go, JVM, Swift, C++, and more)
• Fully configurable via JSON config with pattern overrides and custom paths
• Analysis-only — never deletes, moves, or modifies your files

Requires Python 3.13+ and uv.

# Clone and install
git clone https://github.com/mdemirhan/dux.git
cd dux
uv sync

# Analyze current directory in the interactive TUI
uv run dux

# Analyze a specific path interactively
uv run dux ~/src

# Print a non-interactive summary and exit
uv run dux -n ~/src

# Include apparent (logical) file size column
uv run dux -A ~/src

# Largest temp/build artifacts
uv run dux -t ~/src

# Combine flags: summary + cache + temp
uv run dux -c -t ~/src

# Explicit interactive flag (optional compatibility alias)
uv run dux -i ~/src

To call dux directly from anywhere, add an alias to your shell config (~/.bashrc or ~/.zshrc):

# Using free-threaded Python 3.14t (recommended for best performance)
alias dux='uv run --python 3.14t --project /path/to/dux dux'

# Or with standard Python
alias dux='uv run --project /path/to/dux dux'

Replace /path/to/dux with the actual clone path. Then:

dux ~/src          # Interactive TUI
dux -n ~/src       # CLI summary
dux -i ~/src       # Explicit interactive compatibility flag
dux -v ~/src       # Verbose (shows GIL status, scanner, timing)

Switch views with Tab/Shift+Tab or press the shortcut key directly.

uv run dux [PATH] [OPTIONS]

By default dux launches the interactive TUI. Use --non-interactive / -n to print a summary and exit. The --top-* flags remain composable and imply non-interactive mode for compatibility; --interactive / -i can explicitly override that behavior.

Config file: ~/.config/dux/config.json

Generate a sample config with all defaults:

uv run dux --sample-config > ~/.config/dux/config.json

Key settings:

{
  "scanWorkers": 4,
  "maxDepth": null,
  "topCount": 15,
  "pageSize": 100,
  "overviewTopDirs": 100,
  "scrollStep": 20,
  "maxInsightsPerCategory": 1000,
  "additionalTempPaths": [],
  "additionalCachePaths": [],
  "tempPatterns": [...],
  "cachePatterns": [...],
  "buildArtifactPatterns": [...]
}

Each pattern rule:

{
  "name": "npm cache",
  "pattern": "**/.npm/**",
  "category": "cache",
  "applyTo": "both",
  "stopRecursion": false
}

Measured with hyperfine (5 runs, 1 warmup) on a MacBook Pro M4 with Python 3.14t (free-threaded), 4 workers:

Relative to the fastest (dux --scanner macos):

The macOS scanner (getattrlistbulk) fetches stat info in bulk per directory, avoiding per-file syscalls. Single-threaded du falls further behind as the tree grows. The posix and python scanners are close on macOS because readdir doesn't bundle stat info (unlike Linux), so both end up doing per-file lstat calls.

Note on the du comparison: du -sh only traverses, stats, and sums — dux does all of that plus builds a full in-memory tree, pattern-matches every node against 59 rules (Aho-Corasick + hash lookups), generates categorized insights, and renders Rich output. dux does strictly more work and is still faster with the macOS scanner. The one caveat is that du deduplicates hard-linked files by inode while dux does not, though this is negligible on most home directories.

The scanner is I/O-bound. dux ships three scanner backends and automatically selects the best one for your platform:

Override with --scanner posix|macos|python.

dux supports free-threaded Python (3.13t+). All three C extensions (_walker, _ac_matcher, _prefix_trie) declare Py_MOD_GIL_NOT_USED, enabling true parallel execution without GIL contention. Use --verbose to see GIL status and active scanner at runtime.

When the GIL is disabled, default_scanner() selects PythonScanner — the C readdir wrapper's overhead becomes negligible compared to the parallelism gains from true multi-threading, and the pure Python scanner has the advantage of working through the FileSystem abstraction layer.

Pattern matching (insight generation) is the second-hottest path after scanning. dux avoids naive fnmatch-per-rule by classifying all 59 rules at compile time into fast string operations:

• EXACT — dict lookup on lowercased basename — O(1)
• CONTAINS + ENDSWITH — Aho-Corasick automaton (C extension) for multi-pattern search in a single pass over the path — O(path_length). ENDSWITH suffixes are added as end-only keys, matched only when they occur at the end of the path
• STARTSWITH — PrefixTrie (C extension) walks the basename once, collecting all matching prefixes — O(basename_length) regardless of pattern count
• GLOB — fallback to fnmatch only for patterns that can't be decomposed

Brace expansion ({a,b}) is resolved at compile time. All matcher values are lowercased once at build time; paths are lowercased once per node for case-insensitive matching.

See docs/aho-corasick.md and docs/prefix-trie.md for detailed algorithm explanations, and docs/architecture.md for the full end-to-end pipeline.

# Install with dev dependencies
uv sync

# Run tests
uv run pytest

# Lint and format
uv run ruff check
uv run ruff format

# Type check
uv run basedpyright

MIT