Understand dirgo by driving it A hands-on walkthrough: a working replica of the TUI, a step-through of the message loop, a live simulation of the concurrent scanner, and a clickable map of the codebase. Everything on this page runs locally — no network, no dependencies.

01What dirgo is

dirgo is a terminal disk-usage explorer. You point it at a directory; it lists every child sorted by size, with proportional bars, recursive totals for folders, and single-key navigation into the tree. Think du and ls merged into something you can actually browse.

Under the hood it is a Go program built on Bubble Tea, which implements The Elm Architecture: one immutable model, one Update function, one View function, and side effects expressed as commands that run off the UI thread. That single choice is what makes the rest of the design fall into place — and it is what the next three widgets make visible.

02Drive it yourself

Below is a faithful replica of dirgo's interface running against a synthetic home directory. The layout arithmetic, colour thresholds, fuzzy search, sort order, size formatting, cache behaviour and async line counting are all ported directly from the Go source — so what you see here is what the real tool does.

Click the terminal to focus it, then use the keys. The event log underneath shows what the runtime is doing: which message was delivered, which command was dispatched, and on which goroutine.

Things worth trying

03One keypress, end to end

Everything in dirgo is a message. Nothing mutates state except Update, and nothing blocks the UI except Update and View themselves — both of which are fast by construction.

Step through a complete session below: launching the binary, the first scan finishing, and then a single ↓ keypress causing a line count to appear. The lane badge tells you which goroutine is executing, and the model panel highlights fields that changed on that step.

04Inside a scan

This is where dirgo actually spends its time. When you enter a directory, scanDirectory reads it in one syscall, splits children into files and subdirectories, and then spawns one goroutine per subdirectory to compute its recursive size. Those goroutines are gated by a counting semaphore built from a buffered channel:

sem := make(chan struct{}, minInt(runtime.NumCPU(), 16))

for ri, di := range dirEntryIndices {
	wg.Add(1)
	go func(resultIdx int, info dirInfo2) {
		defer wg.Done()
		sem <- struct{}{}            // acquire — parks here when all slots are taken
		defer func() { <-sem }()     // release — wakes the next parked goroutine

		size, files, dirs := dirSizeRecursive(filepath.Join(absPath, info.name), prog)
		results[resultIdx] = dirResult{index: info.index, size: size,
			childFiles: files, childDirs: dirs}
	}(ri, di)
}
wg.Wait()

Drive the simulator: change the core count, the number of subdirectories, and how evenly the work is distributed. Watch the semaphore slots fill, goroutines park and wake, and the atomic counters climb.

What the simulator is showing you

The full analysis — including the race-safety audit table, why atomic.Int64 rather than the free functions, and the exact tuning thresholds — lives in §8 of the reference guide.

05Codebase map

Nine files, one main package, no internal directories. Click any file to see its role, its key symbols, what it connects to, and what you would change there.

06Where to change what

Practical entry points for common modifications.

Getting the code running

git clone https://github.com/mohsinkaleem/dirgo.git && cd dirgo
make build     # → ./dirgo
make test      # go test -race -v ./...   ← race detector is always on
make bench     # allocation + throughput benchmarks
./dirgo ~      # try it against your own home directory

07Where to go next