dirgo

A fast, minimal and interactive terminal disk usage analyzer built with Go and Bubble Tea. Visualize disk usage, explore directories and files, and find what's eating your disk space — all from your terminal, on macOS, Linux, and Windows.

Features

• Instant directory listing — files appear immediately; directory sizes compute in the background
• Proportional size bars — color-coded percentage bars for quick visual scanning
• Efficient directory scanning — a bounded pool of workers shares the directory walk, so one huge subfolder (node_modules, ~/Library) never serializes the scan; one lstat per file and none per directory
• Smart refresh — checks directory modtime before rescanning; skips unchanged directories
• LRU cache — bounded in-memory cache (100 entries) for instant back-navigation within a session; deleting with d updates cached sizes up the tree instead of forcing a rescan
• Line counting — automatic line count for the selected text file; batch count all with s
• Hex view — built-in hex dump for binary files (xxd on macOS, hexdump fallback on Linux)
• Large file protection — prevents accidentally opening very large blob files
• Fuzzy search — filter entries in real time with subsequence matching
• Symlink detection — symlinks shown with → / ⇢ indicators; symlinked directories can be opened but are never followed when sizing, so nothing is counted twice
• Move to trash — safely delete files/directories with d
• Cross-platform — works on macOS, Linux, and Windows (Quick Look, file open, trash, and hex view adapt per OS)
• CPU profiling — built-in --profile flag for performance analysis

How it compares

dirgo is in the same family as ncdu, gdu, and dust. The differences:

• No up-front scan. ncdu and gdu scan the whole tree before you can browse; dirgo lists the current directory immediately and fills in sizes as they're computed. dust prints a one-shot report rather than an interactive view.
• File-level tools, not just sizes. Line counts, hex view, Quick Look / open, and move to trash are one key away, so you can inspect and clean up without leaving the browser.
• Installs everywhere. One static binary via Homebrew, pip/uv, go install, or the release archives.

Install

Homebrew (macOS / Linux)

brew install mohsinkaleem/tap/dirgo

Install script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/mohsinkaleem/dirgo/main/scripts/install.sh | sh

The script downloads the latest release, verifies its checksum and installs dirgo to /usr/local/bin, or ~/.local/bin if that isn't writable. Set DIRGO_INSTALL_DIR to pick another folder or DIRGO_VERSION (e.g. v1.2.1) to pin a release.

pip / uv (any platform)

pip install dirgo

uv tool install dirgo

Go install

go install github.com/mohsinkaleem/dirgo@latest

Pre-built binaries

Archives for macOS, Linux and Windows (amd64 and arm64) are attached to every release, along with checksums.txt. On Windows, extract dirgo.exe and put it somewhere on your PATH. On macOS, a binary downloaded through a browser is quarantined by Gatekeeper; clear the flag with xattr -d com.apple.quarantine dirgo.

From source

git clone https://github.com/mohsinkaleem/dirgo.git
cd dirgo
make build

Usage

# Analyze current directory
dirgo

# Analyze a specific path
dirgo ~/Documents

# Print version
dirgo --version

# Enable CPU profiling
dirgo --profile /path/to/dir

Keybindings

Architecture

For a full walkthrough of the design — component breakdown, message flow, the scanning pipeline, and a deep dive on the concurrency model — see the architecture guide.

Prefer to learn by doing? The interactive tour lets you drive a working replica of the TUI in your browser, step through the message loop one frame at a time, and run the concurrent scanner with adjustable core counts.

main.go        Entry point, --profile/--version flags, Bubble Tea program setup
model.go       Application state, Update loop, message handling
scanner.go     Directory scanning with os.ReadDir + manual recursion, bounded concurrency
cache.go       Bounded in-memory LRU cache with eviction
entry.go       FileEntry data model, sorting, filtering, fuzzy match
render.go      Row rendering, header/footer, help overlay
keys.go        Key bindings
styles.go      Lipgloss color and style definitions (pre-defined bar color styles)
utils.go       Formatting, line counting (bytes.Count + sync.Pool), helpers

Scanning Pipeline

1. scanDirectory() calls os.ReadDir to read the directory in a single syscall, immediately stats files, and separates directories from files.
2. Directory sizes are computed in parallel using dirSizeRecursive() — a manual recursive function using os.ReadDir that avoids the overhead of filepath.WalkDir. Bounded concurrency is enforced via a semaphore (CPU count, max 16).
3. File stat is parallelised for directories with 20+ files to leverage multi-core CPUs.

Caching

• In-memory: LRU cache holding up to 100 directory scan results. Accessed on navigation; updated on scan completion.
• On-disk: Not implemented as of now. Wanted to keep it simple and deterministic.

Smart Refresh

Pressing r compares the directory's current modtime against the cached value. If unchanged, the rescan is skipped entirely (~microseconds). If changed, a full rescan is triggered.

Development

# Run tests
make test

# Run benchmarks
make bench

# CPU profile a benchmark
make profile-cpu

# Memory profile
make profile-mem

# Build cross-platform release binaries
make release

Requirements

• Go 1.25+ (only needed to build from source or go install)
• macOS / Linux / Windows

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development setup, and please follow the code of conduct. To report a security issue, see SECURITY.md.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT