3.8 KiB
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:
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:
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.