dirgo

A fast, minimal and interactive terminal directory analyzer built with Go and Bubble Tea. Visualize disk usage, explore directories, files, and identify space hogs — all from your terminal.

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, and cache paths adapt per OS)
• CPU profiling — built-in --profile flag for performance analysis

Install

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

Homebrew

brew tap mohsinkaleem/tap
brew install dirgo

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 docs/architecture.html.

Prefer to learn by doing? docs/explore.html is an interactive tour: 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.21+
• macOS / Linux / Windows

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

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