I built a TUI dotfile browser in Go – here's why and how

Riccardo Cataldi — Sat, 30 May 2026 14:11:17 +0000

RiccardoCataldi / dotty

TUI dashboard for browsing and previewing dotfiles in your home directory. Fuzzy search, tree view, zero config.

dotty

Terminal UI for browsing dotfiles under your home directory. Run it from anywhere — it always scans ~, shows an expandable tree on the left, file preview on the right, and a fuzzy finder to jump to any path quickly.

Install

Run dotty from any directory once the binary is on your PATH.

Pre-built binary (recommended)

Download from Releases. Replace VERSION with the latest tag (e.g. v0.1.1).

Platform	Asset
Linux x86_64	`dotty_Linux_x86_64.tar.gz`
Linux ARM64	`dotty_Linux_arm64.tar.gz`
macOS Intel	`dotty_Darwin_x86_64.tar.gz`
macOS Apple Silicon	`dotty_Darwin_arm64.tar.gz`

VERSION=v0.1.1
curl -sL "https://github.com/RiccardoCataldi/dotty/releases/download/${VERSION}/dotty_Linux_x86_64.tar.gz" | tar xz
install -m 755 dotty ~/bin/   # or: sudo install -m 755 dotty /usr/local/bin/

Ensure ~/bin or /usr/local/bin is on your PATH.

From source

Requires Go 1.22+.

git clone https://github.com/RiccardoCataldi/dotty.git
cd dotty
go install ./cmd/dotty

The binary is installed to $(go env GOPATH)/bin/dotty (usually ~/go/bin/dotty). Add that directory to your…

View on GitHub

My home directory has 140+ hidden files and folders.

.aws/credentials, .ssh/config, .cursor/rules, .config/nvim/, .gitconfig, Claude's JSON config somewhere in .config... Every time I needed to tweak something I had to remember where it lived, cd there, find the right file, open it. Then repeat the next time I forgot.

I looked for a tool that would solve this. chezmoi and stow are great but they solve a different problem — syncing dotfiles across machines. File managers like yazi are generic and don't give you a unified view of just your config files. Nothing gave me what I wanted: a single command that aggregates all my dotfiles in one searchable view, from wherever I am in the terminal.

So I built dotty.

What it does
Run dotty from any directory. It scans ~ and gives you:

An expandable tree of every dotfile and dot-directory
Live file preview on the right panel
Fuzzy finder (/) to jump to any config in seconds
e to open in $EDITOR
y to copy the path to clipboard

Single static binary, zero config, works over SSH and inside tmux.

Why Go
This was my first real Go project shipped end to end. I chose Go for two reasons:
Single static binary. No runtime dependencies, no Python virtualenv, no Node modules. go build → one file → move it to /usr/local/bin/ → done. This matters for a tool you want to install and forget about.
Bubble Tea. Charmbracelet's TUI framework for Go is exactly what I needed. It follows the Elm architecture (Model, Update, View) which makes TUI state management surprisingly clean. Tools like lazygit, lazydocker, and k9s are all built on similar patterns — I wanted that same feel.

The stack

Bubble Tea — TUI framework, Elm architecture
Bubbles — pre-built TUI components (viewport, textinput)
Lipgloss — CSS-like terminal styling
GoReleaser + GitHub Actions — multi-platform releases (Linux + macOS, x86 + ARM)

What I learned
Bubble Tea's model is great once it clicks. The idea is that your entire application state lives in one struct, and every keypress goes through a pure Update function that returns a new state. Coming from imperative code it feels weird at first, then it feels obvious.
Terminal layout is harder than it looks. Getting two panels to resize correctly when the terminal window changes, keeping scroll state in sync with the selected file, handling edge cases like empty directories or binary files — there's more surface area than I expected.
GoReleaser is worth learning. Setting up multi-platform builds with checksums, a proper install script, and GitHub Release assets took maybe two hours but now releases are one git tag away. Should have done this from day one.

What's next
The current version covers navigation and preview. What's missing for a complete workflow:

Rename and delete directly from the TUI
Grep across all dotfile content
Syntax highlighting in the preview panel

If you work a lot in the terminal and have the same dotfile chaos problem, give it a try:
bashgo install github.com/RiccardoCataldi/dotty/cmd/dotty@latest
Or grab a pre-built binary from the releases page.
Feedback welcome — especially on the Go code itself, since this is my first shipped Go project.