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 — uses os.ReadDir + manual recursion to minimize syscalls; parallel stat with bounded concurrency
• 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
• 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
• 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

pip / uv (any platform)

pip install dirgo

uv tool install dirgo

Go install

go install github.com/mohsinkaleem/dirgo@latest

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