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

```bash
pip install .
```

For editable local development:

```bash
pip install -e '.[dev]'
```

After installation, the application command is:

```bash
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:

```bash
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:

```bash
source ~/.bashrc
```

Or:

```bash
source ~/.zshrc
```

Then use:

```bash
cd_
```

## Uninstall

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

```bash
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:

```bash
make dev
```

Run the application in development mode:

```bash
python -m app.main
```

Useful development commands:

```bash
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`.