cd-browser

cd-browser is a terminal-native directory navigator for fast filesystem browsing from the command line.

It provides an interactive interface for exploring directories with the keyboard and returns the selected path at the end of the session so shell wrappers can change the current shell directory.

Documentation

See the documentation index:

docs/index.md

Features

• Interactive terminal directory browser
• Keyboard-driven navigation
• Parent directory entry via ..
• Expand and collapse directory trees
• Session navigation history support in the application state
• Installable CLI command: cd_browser

Installation

Install the project in user mode:

pip install .

For editable local development:

pip install -e '.[dev]'

After installation, the application command is:

cd_browser

When the interactive session exits, the program prints the final selected directory path.

Shell Integration For cd_

Because a Python subprocess cannot directly change the parent shell directory, use a shell wrapper that captures the final path printed by cd_browser.

Bash or Zsh example:

cd_() {
  local target
  target="$(cd_browser)" || return

  if [ -n "$target" ] && [ -d "$target" ]; then
    cd "$target"
  fi
}

After adding the function to your shell profile, reload it:

source ~/.bashrc

Or:

source ~/.zshrc

Then use:

cd_

Uninstall

If the project was installed with pip, remove it with:

pip uninstall cd-browser

If you also added the cd_ shell wrapper, remove that function from your shell profile and reload the shell configuration.

Developer Setup

Recommended setup:

make dev

Run the application in development mode:

python -m app.main

Useful development commands:

make fix
make quality
make run

Template Origin

This project was created from the Python AI Dev Template.

The original template documentation has been preserved in README_TEMPLATE.md so the project-specific README can focus on cd-browser usage and development.

For the original template setup, conventions, and generic workflow notes, see README_TEMPLATE.md.