Project TUI Manager

A premium, feature-rich Terminal User Interface (TUI) designed to streamline local programming project discovery, dependency management, and container execution. Built with Python and Textual, it provides a high-performance, keyboard-driven dashboard for developers to manage workspaces without leaving the terminal.

---

🎨 Premium Design & Aesthetics

The Project TUI Manager is built with modern terminal design principles, utilizing an elegant dark-theme palette (#0f172a Slate/Zinc background) combined with clean borders, high-contrast states, and subtle micro-animations for an interactive experience.

• Layout Structure: Split-pane view featuring an adaptive project directory tree (left) and tabbed control panels (right).
• Responsive Rendering: Columns and text wrap automatically to fit container bounds, eliminating horizontal scroll clutter.
• Fluid Navigation: Tabs transition instantly with standard keyboard shortcuts.

---

🚀 Key Features

1. Global CLI Invocation (ptui)

• Automated installers register the executable command ptui globally across Linux, macOS, and Windows.
• Launch the TUI interface instantly from any terminal prompt or directory simply by typing ptui.

2. Global Persistent User Configuration

• Remembers user preferences persistently in ~/.config/projects-tui/config.json (or OS user profile directory).
• Automatically restores your selected project root directory and preferred CLI code editor across terminal sessions and locations.

3. Workspace Directory Scanning

• Instantly scans and indexes all subdirectories in your configured projects root path.
• Supports real-time UI updates: newly created projects automatically focus and center on screen.
• Simple prompt-based dialogs to safely initialize templates or delete obsolete directories directly.

4. Native README & Overview Tab

• Automatically parses and renders local README.md files with rich markdown typography.
• Full mouse-wheel and keyboard scrolling (w for up, s for down).

5. Integrated Docker Control Panel

• Automatically scans selected directories for docker-compose.yml or compose.yaml specifications.
• Formats container status in a clean table showing container names, image names, live status, and exposed ports.
• Smart Dimming: Stopped or inactive containers are dynamically greyed out to maintain strong visual hierarchy.
• Non-blocking background executors for container life cycles (Start, Stop, Restart) with temporary loading states.

6. Dependency & Environment Manager (uv / pip)

• Automatically scans project files for pyproject.toml (PEP 621 / Poetry specs) and displays dependencies in a clean, vertical-only scroll table.
• Features a single-click environment initializer using uv. Running uv init automatically updates all project packages via requirements.txt if available.

---

⚙️ Easy Installation & Setup

Ensure you have Python 3.8+ installed.

Linux / macOS (One-Step Automated Installer)

Run the automated installation script:

./install.sh

The installer automatically builds the .venv virtual environment, installs dependencies, and registers the global ptui command in ~/.local/bin.

Launch the app from anywhere:

ptui

Windows (One-Step PowerShell Installer)

Open PowerShell in the project directory and run:

.\install.ps1

The installer configures the Python virtual environment and adds ptui to your User PATH.

Launch the app from any Command Prompt or PowerShell terminal:

ptui

Manual Setup

# 1. Create environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install requirements
pip install -r requirements.txt

# 3. Launch TUI
python3 app.py

---

🎮 Keyboard Bindings

Quickly navigate the entire interface using global and context-sensitive key bindings:

Global Bindings

• q: Quit the application
• n: Open new project dialog screen
• o / Enter: Open the currently selected project in your preferred text editor
• d: Delete the selected project (prompts delete dialog)
• Left Arrow / Right Arrow: Cycle active detail tabs on the right pane

Content Pane Controls

• w: Scroll Up (Readme, Docker table, and Environment table)
• s: Scroll Down (Readme, Docker table, and Environment table)

Action Buttons

• Docker Control Tab:
  • 1: Start containers (docker compose up)
  • 2: Stop containers (docker compose down)
  • 3: Restart containers (docker compose restart)
• Environment Tab:
  • 1: Run Environment Initialization (uv init)

---

🛠️ Technology Stack

• Core Framework: Textual - Asynchronous TUI framework for Python.
• Formatting Engine: Rich - Terminal formatting, colors, and layout utilities.
• Environment Engine: uv - Fast Python package installer and manager.