ShScriptHub

Scans your project, detects environments and runs scripts.

A .sh script runner for anyone tired of hopping between folders and scripts. It scans your selected folder to build a centralized hub, opens a new terminal per script for easier project management and auto-detects Python environments.

Preview

Features

• Toolbar and navigation
• Sidebar
• Detail panel
• Live metrics
• Script viewer
• Scheduler
• System notifications

Toolbar and navigation

Compact toolbar at the top of the window:

• Project - Set project path | Refresh to rescan scripts

• Terminal - Set Git Bash path

• Venv - Set venv activate path for scripts that interact with Python | Clear venv path to revert to auto-detect

• Notification - Dropdown to turn scheduler notifications On or Off (persisted in config). When On, a toast is shown for each scheduler-related event.

• Theme toggle - Switch between dark and light themes (persisted across restarts)

• Page selector - Switch between Home (script detail panel) and Scheduler (schedules and run history). The sidebar remains visible in both views.

All settings, per-script categories, and favorites are stored in config.json in the app directory.

Sidebar

Scripts are listed in a collapsible folder tree on the left panel:

• Favorites section - Favorited scripts are pinned at the top.
• Project tree - Scripts grouped by their first-level folder. Folders can be expanded or collapsed.
• Search - Filters the tree by folder or file name as you type.
• Filter - Dropdown to show All, Backend, Frontend, or Running scripts only.
• Running indicator - A dot next to each script shows whether it is currently running.
• Selection - Clicking a script loads its details in the detail panel.

Detail panel

The right panel shows the selected script's full information and controls:

• Name and path - Script name and relative path from project root.
• Category - Per-script category selector (None, backend, frontend). Defaults are inferred from folder name.
• Env - Detected environment for the script (.venv, venv, node_modules, or configured venv path).
• Status - Idle, Running, or Stopped.
• Favorite - Star button to pin or unpin the script.
• Run - Opens the configured terminal with CWD set to the script's folder.
• Kill - Stops only the process tree launched by the app for that script.

Live metrics

When a script is running, the detail panel shows these metrics updated every second:

• CPU % - Current CPU usage.
• RAM (RSS) - Resident memory in use (MB).
• RAM % - Share of system RAM.
• Elapsed - Time since the script started.
• Peak memory - Maximum RSS reached (MB).
• CPU time - Total CPU time consumed.
• Threads - Number of threads.

Script viewer

The detail panel includes a read-only viewer that displays the selected script's source code with syntax highlighting:

• Shell keywords, strings, variables, comments, shebangs, and numbers are each coloured distinctly.
• Line numbers are shown in the left gutter.
• Horizontally scrollable for long lines.
• Colors adapt to the active theme (dark or light).

Scheduler

A dedicated Scheduler page (via the Home | Scheduler selector) lets you run scripts automatically on a schedule.

Schedules view:

• New Schedule - Create time-based (specific hour:minute) or interval-based (every N minutes/hours) schedules.
• Filters
  • Schedule name - Free-text field with autocomplete: type to filter the list of schedule names; the dropdown suggests existing schedule names and narrows as you type.
  • Script - Dropdown of project scripts to show only schedules that run that script.
• Table columns - Name, Script, Rule, Next Run, Status, Enabled toggle, Delete.
• Live countdown - When a schedule is enabled, the Next Run column updates every second. When disabled, shows "Disabled".
• Interval reset on enable - Toggling a disabled interval schedule back ON resets the countdown from the full interval.
• Row actions - Click a row to edit; use the toggle to enable/disable; use the trash icon to delete.

History view:

• Filters
  • Schedule name - Free-text field with autocomplete: type to filter by schedule name; the dropdown lists schedule names that appear in history and filters as you type;
  • Script - Dropdown of scripts that appear in history to show only runs for that script.
  • Status - All, started, killed, exited, failed.
• Columns - Schedule name, Script path, Time, Status.
• Sub-row details - Started and Finished timestamps on separate lines; for killed runs, shows "Previous instance terminated by scheduler".
• Manual kill detection - When you manually kill a scheduled script, the history entry is updated to "killed" with the correct finished time.

Terminal log visualization:

• Every scheduler run’s terminal output (stdout and stderr) is captured and stored, so you can review it later.
• The History tab uses a two-section layout: the history list on top and a Run log viewer below.
• Click a history row to load that run’s full terminal log in the viewer. If there is no log for that run, the viewer shows "No log recorded."
• The log viewer is read-only and scrollable.
• Logs are keyed by the same run id as in scheduler_history.json and persisted in Scheduler/history_logs.json; temporary capture files live in Scheduler/logs/.

Schedules and run history are stored in the Scheduler folder: Scheduler/schedules.json, Scheduler/scheduler_history.json, Scheduler/history_logs.json. Run logs are written to Scheduler/logs/.

System notifications

When notifications are enabled (Toolbar → Notification → Scheduled: On), the app shows a small toast in the bottom-right of the screen for scheduler events only:

• Scheduled run started - The script process was started by the scheduler.
• Scheduled run finished - The run exited on its own.
• Scheduled run killed - The run was stopped (by you or by the scheduler before the next run).
• Scheduled run error - The run failed to start (e.g. script not found, not under project path, or launch exception).

Each toast shows the schedule name, script name, rule (e.g. interval and duration), and time until the next run. Toasts use the same theme as the app (dark or light), stay on top of other windows, auto-close after a few seconds, and can be closed early with the close button. Multiple toasts are shown one after another.

How scripts are discovered

The app scans the selected folder recursively and lists every .sh file. Names are shown relative to the project root (e.g. backend/run.sh, scripts/docker-up.sh). Scripts run with CWD = their own folder, not the project root.

Env is detected in the script's folder: .venv, venv, or node_modules. For scripts in category backend, a configured venv path (see Toolbar) overrides auto-detection.

Example layout (any structure works):

your-project/
├── backend/          # auto = backend; .venv/venv
├── frontend/         # auto = frontend; node_modules
├── api/              # category None
└── scripts/          # category None

Setup & Run

1. Clone or open the project

git clone https://github.com/leobrqz/ShScriptHub.git
cd ShScriptHub

2. Install dependencies

pip install -r requirements.txt

3. Run the app

python src/main.py

Credits

• Icon made by jungsa

Author

Leonardo B.

• GitHub: leobrqz
• LinkedIn: leonardobri

Check out my other projects <3