cd-browser/README.md

cd-browser

Stop typing paths. Browse them.

cd-browser is a fast keyboard-driven directory navigator for the terminal. It lets you explore directory trees visually and jump to any folder instantly.

Why cd-browser?

Working in the terminal often means:

• typing long directory paths
• navigating deep folder trees
• repeating cd .. multiple times

cd-browser provides an interactive terminal UI that allows you to browse directories with the keyboard and return the selected path directly to your shell.

Features

• 🚀 Fast visual navigation of directory trees
• ⌨️ Fully keyboard-driven workflow
• 🌲 Expand and collapse directories
• 📜 Navigation history inside the session
• 🖥 Native terminal interface
• 🔁 Works with Bash, Zsh and other shells
• ⚡ Returns the selected path to the shell

Quick Demo

Run:

cd_

Browse directories using the arrow keys and press Enter to jump directly to the selected folder.

Documentation

See the documentation index:

docs/index.md

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.