cd-browser/docs/project_overview.md

Project Overview --- cd-browser

Author: Saky

This document provides a quick introduction to the cd-browser project and guides readers through the repository structure, documentation, and development workflow.

---

What is cd-browser?

cd-browser is a terminal-based directory navigator that allows users to browse directories interactively and then change the working directory of their shell.

It solves a common shell limitation:

A program cannot directly change the directory of its parent shell.

The solution is:

1. The program returns a directory path.
2. A shell wrapper function performs the actual cd.

---

Example usage

cd_

The command launches an interactive terminal browser.

After navigating and exiting:

• the selected directory is returned
• the shell wrapper changes the working directory.

---

Key Features

• interactive terminal navigation
• tree-style directory browsing
• expandable directories
• keyboard-driven interface
• directory navigation history
• clean shell integration
• installable as a CLI tool
• tested Python codebase
• automated formatting and linting

---

Repository Structure

cd-browser/

README.md                → main project documentation
README_TEMPLATE.md       → original template documentation

docs/
    development-journey.md
    ai-development-playbook.md
    architecture.md

specs/
    cd_browser_spec.md

src/
    app/
        cli.py
        filesystem.py
        history.py
        navigator.py
        ui.py
        main.py

tests/

scripts/

pyproject.toml
Makefile

---

Documentation Guide

The repository includes several documents explaining the project from different perspectives.

README.md

Quick introduction and installation instructions.

specs/

Functional specifications of the application.

docs/development-journey.md

Explains how the project was built step-by-step using AI coding agents.

docs/ai-development-playbook.md

Reusable methodology for building applications using AI development workflows.

docs/architecture.md

Technical architecture of the application.

---

Installation

Clone the repository:

git clone https://gitea.sakydogalo.es/saky/cd-browser.git
cd cd-browser

Install the tool:

pip install .

---

Shell Integration

Add this function to your shell configuration (~/.zshrc):

cd_() {
  local target
  target="$(cd_browser)"
  if [ -n "$target" ] && [ -d "$target" ]; then
    cd "$target"
  fi
}

Reload the shell:

source ~/.zshrc

Now you can run:

cd_

---

Development Setup

For contributors or developers:

make dev
source .venv/bin/activate

Run the application:

python -m app.main

---

Quality and Validation

The project uses automated tools to ensure code quality.

Tools:

• black (formatting)
• ruff (linting)
• mypy (type checking)
• pytest (testing)

Commands:

make fix
make quality
make ci

---

AI-Assisted Development

This project was built using a structured AI-assisted development workflow.

Key ideas:

• architecture defined by a human
• AI agents used for focused implementation tasks
• strict validation loops
• small scoped prompts

More information:

docs/ai-development-playbook.md

---

Status

Current version:

v0.1.0

The project is stable and functional as a minimal terminal directory navigator.

Future improvements may include:

• improved navigation model
• fuzzy search
• bookmarks
• persistent history

---

License

See the LICENSE file.

---

End of document.