~/projects/work/projects/client-name/frontend/app
~/projects/personal/rust/file-finder
~/projects/side-projects/2024/some-idea

cd projects
cd work
cd client-name
cd frontend
cd app
nvim .

I like keeping my projects organized. Maybe a little too organized.

My folder structure looks something like this:

~/projects/work/projects/client-name/frontend/app
~/projects/personal/rust/file-finder
~/projects/side-projects/2024/some-idea

For a while, my workflow to open a project was:

cd projects
cd work
cd client-name
cd frontend
cd app
nvim .

Six commands just to start working. Every. Single. Time.

I tried tools like fzf and ranger. They’re great, but they didn’t quite solve my problem. fzf finds files, but after selecting one, I’m still in my original directory. Ranger lets me browse around, but it’s more of a file manager than a quick project launcher.

What I really wanted was simple: type the project name, press Enter, and be there. No extra steps.

I couldn’t find anything that did exactly that. So I built it.

---

The idea

I was also looking for an excuse to learn Rust. Building something I’d actually use every day seemed like the right approach — not another tutorial project that sits in a folder forever.

The core concept was straightforward:

1. Cache my directory structure so searching is instant
2. Fuzzy search to find what I need
3. When I select a directory, actually cd into it in my shell

That last part is the trick. Most terminal tools run in a subprocess — they can’t change your shell’s working directory. I solved this with shell integration. You add one line to your .zshrc:

eval "$(ff init zsh)"

Now when I press Enter on a directory, my terminal is actually in that directory. I just type nvim . and I’m working.

The workflow became:

ff       # launch
# type "client-name"
# press Enter
nvim .   # already there

That’s it. No more cd chain.

---

What it turned into

What started as a simple project launcher grew into a full terminal file explorer. Once I had the foundation, I kept adding things I found useful:

Fuzzy search — Local search in the current directory, or prefix with / for global search across your entire cached directory tree.

File previews — Syntax highlighting for code, image rendering (in supported terminals), PDF text extraction, hex view for binaries. It’s useful to see what’s in a file before opening it.

Vim-style navigation — h, j, k, l to move around. i to search. Muscle memory from Neovim transfers directly.

Dual-pane mode — Side-by-side file management for when you need to copy or move files between directories. Press p to cycle through view modes.

IDE integration — Open files directly in Neovim, VS Code, or Zed. No need to copy the path manually.

Real-time updates — File system watching means if something changes in the directory, you see it immediately.

---

Lessons from building it

A few things I learned along the way:

Caching matters. The first time you run ff, it builds a cache of your directory structure. After that, global search is instant. Without caching, searching a large directory tree would be painfully slow.

Rust’s ecosystem is solid. Libraries like ratatui for terminal UI, syntect for syntax highlighting, and fuzzy-matcher made this possible without reinventing everything.

Build something you’ll use. I use ff dozens of times a day. That motivation kept me going when I hit roadblocks.

---

Try it

If you’re on macOS or Linux:

brew install anthonyamaro15/tap/ff
eval "$(ff init zsh)"  # add to your .zshrc

Then just run ff and start typing.

The repo is at github.com/anthonyamaro15/file-finder-rust. Feedback, issues, and PRs are welcome.

If you’ve ever been frustrated by cd-ing five times to reach a project, give it a shot.