catnav is a Finder-style Miller-column directory navigator for the terminal. It helps you explore unfamiliar or deep directory trees without bouncing between cd and ls or memorizing paths.
Homebrew:
brew install andytyler/tap/catnavor:
brew tap andytyler/tap
brew install catnavnpm:
npm install -g catnavFrom source:
git clone https://github.com/andytyler/catnav.git
cd catnav
npm install -g .catnavOn the first interactive run, catnav configures d in your current shell config and exits.
d will not be available in the current shell until you reload that config.
Then reload your shell.
Use d for the normal workflow: it opens catnav and changes your shell to the selected directory.
Use catnav when you want the raw selector to print the selected directory path.
# zsh
source ~/.zshrc
# bash
source ~/.bashrc
# fish
source ~/.config/fish/config.fish
d
d ~/src
catnav
catnav ~/srcUse the arrow keys to move between columns, press / to filter the active column, . to toggle hidden entries, and Enter to return the selected directory.
Run catnav once in an interactive terminal. It configures d in your current shell config and exits.
catnavThen reload your shell or open a new terminal tab/window. After that:
d
d ~/src
d --helpd opens catnav and changes your shell to the selected directory.
catnav opens the selector and prints the selected directory path.
If you prefer manual setup, source the helper directly from shell/catnav.zsh, shell/catnav.bash, or shell/catnav.fish.
| Key | Action |
|---|---|
Up / Down |
Move within the active column |
Left |
Move to the previous column, or to the parent directory from the first column |
Right |
Open the selected directory in a new column |
/ |
Filter the active column by name |
Ctrl-U |
Clear the current filter |
. |
Toggle hidden files |
Enter |
Return the selected directory and exit |
Esc, q, Ctrl-C |
Cancel |
Enteralways returns a directory path.- If a directory is selected,
Enterreturns that directory. - If a file is highlighted,
Enterreturns the active column's directory instead of a file path. Escclears an active filter first; if no filter is active, it cancels.- The
dshell helper uses--result-fileinternally so it cancdwithout printing the path.
catnav --help| Option | Description |
|---|---|
--depth N |
Breadcrumb depth for the path display (default: 6) |
--max-cols N |
Cap the number of visible columns |
--result-file PATH |
Write the selected directory to a file instead of stdout |
--help |
Show built-in help |
- Large monorepos where you know the area but not the exact path
- Unfamiliar codebases you just cloned or inherited
- Deeply nested config, project, or build directories
- "It's somewhere under here" navigation where fuzzy matching is not enough
| Tool | Best for | catnav is better when... |
|---|---|---|
| Tab completion | You already know the destination or most of the path | You're discovering, not recalling |
zoxide, z, autojump |
Revisiting places from shell history | You haven't been there before |
fzf |
Name search is enough | You want parent/child context and spatial orientation |
ranger, nnn, vifm |
Full terminal file management | You just need to pick a directory, fast |
Built by Andy Tyler ajt.dev. Open source under the MIT License.
