catnav

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.

Install

Homebrew:

brew install andytyler/tap/catnav

or:

brew tap andytyler/tap
brew install catnav

npm:

npm install -g catnav

From source:

git clone https://github.com/andytyler/catnav.git
cd catnav
npm install -g .

Quick Start

catnav

On 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 ~/src

Use the arrow keys to move between columns, press / to filter the active column, . to toggle hidden entries, and Enter to return the selected directory.

Shell Integration

Run catnav once in an interactive terminal. It configures d in your current shell config and exits.

catnav

Then reload your shell or open a new terminal tab/window. After that:

d
d ~/src
d --help

d 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.

Keybindings

| 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 |

Behavior

• Enter always returns a directory path.
• If a directory is selected, Enter returns that directory.
• If a file is highlighted, Enter returns the active column's directory instead of a file path.
• Esc clears an active filter first; if no filter is active, it cancels.
• The d shell helper uses --result-file internally so it can cd without printing the path.

CLI Options

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 |

Use Cases

• 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

Why Not X?

| 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 |