Internal Design

System Architecture

How Clingy orchestrates CLI tools, auto-discovers commands, and renders interactive menus.

01 // Overview

Clingy is designed around a modular, auto-discovering architecture. Instead of manually registering commands in a central router, the framework dynamically loads any valid command class found in the commands/ directory.

The core innovation is the dual-mode execution: commands can be invoked directly via traditional CLI arguments, or navigated interactively via a generated fzf menu tree.

02 // Directory Map

clingy/
├── commands/          # Framework commands
│   ├── base.py        # Abstract base class
│   ├── init.py        # Project initialization
│   └── __init__.py    # Command discovery
│
├── core/              # Core utilities
│   ├── discovery.py   # Context detection
│   ├── logger.py      # Logging functions
│   ├── menu.py        # Interactive menu system (fzf)
│   └── stats.py       # Statistics tracking
│
├── cli.py             # CLI entry point (orchestrator)
└── config.py          # Framework configuration

03 // Execution Flow

01

Entry Point

User invokes clingy. cli.py initializes the orchestrator.

02

Context Detection

discovery.py searches upwards to find the project root and loads config.py.

03

Command Auto-Discovery

Framework scans commands/ and instantiates all classes inheriting from BaseCommand.

04

Menu Tree Construction

Calls get_menu_tree() on all commands to build the hierarchical navigation structure.

05

Interactive Loop

Passes the tree to MenuRenderer which manages the fzf subprocess until a leaf node action is executed.