# cd_ — Terminal Directory Navigator ## Overview `cd_` is an interactive terminal utility designed to make directory navigation faster and more intuitive directly from the command line. Instead of manually typing `cd` commands, users can browse directories using a keyboard-driven interface. The tool behaves like a **lightweight directory browser inside the terminal**. --- # Goals The utility should provide: - fast directory navigation - keyboard-driven interface - minimal latency - intuitive exploration of directory trees - ability to preview folder structure without entering directories The tool must remain **lightweight and terminal-native**. --- # Execution The tool is executed from the terminal: ```bash cd_ ``` When executed, it opens an **interactive terminal navigation interface**. --- # Interface Behavior The interface displays: - the current working directory - a list of subdirectories - a special entry: ``` .. ``` which navigates to the parent directory. Example: ``` /home/user/projects ▶ backend ▶ scripts docs .. ``` --- # Directory Indicators Directories must visually indicate whether they contain subdirectories. Recommended symbols: | Symbol | Meaning | |------|------| | ▶ | collapsed directory containing subdirectories | | ▼ | expanded directory | | space | directory without subdirectories | Example: ``` ▶ backend ▼ scripts build deploy docs ``` --- # Navigation Controls ## Arrow Up / Arrow Down Move selection between entries. --- ## Enter Enter the selected directory. If `..` is selected, navigate to the parent directory. --- ## ESC Exit interactive mode. The shell should remain in the directory currently selected. --- # Tree Expansion Users should be able to explore directory structure without entering directories. ## Arrow Right Expand the selected directory. Example: Before: ``` ▶ scripts ``` After pressing →: ``` ▼ scripts build deploy tools ``` --- ## Arrow Left Collapse expanded directory. --- # Navigation History The application maintains a session navigation history. --- ## h Display navigation history. The user can select a previous directory from the list. --- ## b Navigate backward in history. --- ## f Navigate forward in history. --- # UI Principles The interface must be: - responsive - minimal - keyboard-focused - easy to understand visually --- # Future Extensions These features are optional and may be added later. ## Search Mode Activated by pressing: ``` / ``` Allows filtering directories by name. --- ## Favorites Mark current directory: ``` m ``` Open favorites: ``` F ``` --- # Technical Constraints The implementation must: - be written in Python - follow the repository coding standards - pass formatting, linting, typing, and tests Validation commands: ``` make fix make quality ``` --- # Installation Requirements The tool must support two usage modes. ## Developer Mode Clone repository and run: ``` make dev ``` Then execute: ``` python -m app.main ``` --- ## User Mode (Installable CLI) The tool should be installable as a CLI command. Example: ``` pip install . ``` After installation, users should be able to run: ``` cd_ ``` directly from the terminal. --- # Shell Integration Constraint Because a subprocess cannot change the parent shell directory, the tool must output the selected directory path. Shell integration should be implemented using a wrapper function. Example: ```bash cd_() { cd "$(cd_browser)" } ``` --- # MVP Scope The first version must include: - directory navigation - tree expansion - keyboard controls - session history - terminal interface Advanced features are optional. --- # Summary `cd_` is a terminal-native interactive directory navigator designed to accelerate filesystem navigation while remaining lightweight and keyboard-focused.