masu-terminal-installer

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

masu-terminal-installer

★ 9 Open GitHub ↗

Automatic ZSH + Powerlevel10k installer for Linux and Termux

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MASU Terminal Installer

![Linux](https://img.shields.io/badge/platform-Linux-green)
![Python](https://img.shields.io/badge/language-Python%20%2B%20Bash-blue)
![Version](https://img.shields.io/badge/version-v10.0-blue)
![Open Source](https://img.shields.io/badge/license-MIT-orange)
![Status](https://img.shields.io/badge/status-active-success)

MASU Terminal Installer sets up a modern **ZSH development terminal environment** — ZSH, Oh My Zsh, Powerlevel10k, and a curated plugin set — through a mouse-driven, fully clickable installer that runs entirely in your terminal.

It installs and configures a professional terminal setup used by developers, Linux enthusiasts, and cybersecurity learners.

Run `./install.sh` and it takes care of everything: detecting your OS, setting up a private Python environment (no manual `venv`/`pip` steps needed), and launching the installer — checkboxes, radio buttons, a live progress bar, all clickable.

---

# Features

✔ **Mouse-Driven Installer** — checkboxes, radio buttons, and a live progress bar, fully clickable, no menus to type numbers into

✔ **Zero Manual Setup** — `./install.sh` handles Python, the virtual environment, and dependencies automatically; no `pip install` or `venv` steps for you to run

✔ **3 Theme Options** — Minimal, Cyber, or P10K interactive wizard

✔ **Fastfetch Startup Choice** — opt in or out during install

✔ **Zero-Config Termux Support** — automatic mobile-optimized theme

✔ **Marker-based Configuration** — safe, re-runnable `.zshrc` updates

✔ **Integrated FZF** — fuzzy history search and navigation in your finished shell

✔ **Custom Fastfetch** — lightweight, compact MASU-themed info

✔ **Per-distro Update Alias** — `update` command works correctly on every OS

✔ **Automatic Nerd Font Install** — MesloLGS NF installed for correct P10K icon rendering

✔ **Retry on Flaky Connections** — all clones retry automatically on network failure

✔ **Visible Sudo Prompts** — the installer steps out of the way for a real, typeable password prompt whenever sudo is needed, instead of hiding it behind the UI

✔ Works on Linux and Termux

---

# Supported Systems

The installer automatically detects your system.

Currently supported systems include:

* Arch Linux / BlackArch / Manjaro
* Ubuntu / Debian / Kali / Parrot
* Fedora / RHEL / Rocky
* OpenSUSE
* Termux

Other distributions may also work if they use compatible package managers.

---

# Installation

```
git clone https://github.com/Maty156/masu-terminal-installer.git
cd masu-terminal-installer
chmod +x install.sh
./install.sh
```

That's it — `install.sh` handles everything else:

1. Detects your OS
2. Asks for your sudo password once, up front, in a normal visible prompt (only if needed)
3. Installs Python if it's missing
4. Creates a private virtual environment in `.masu-venv/` (hidden in the project folder — never touches your system Python, and is reused instantly on future runs)
5. Installs `textual` into that environment
6. Launches the mouse-driven installer

You will not need to run `pip install`, `python -m venv`, or activate anything yourself — `install.sh` is the only command you need.

### About sudo

If sudo access is needed and isn't already cached, the installer will briefly hand control back to your real terminal so you can type your password normally — you'll see this happen, it's not a bug. Once confirmed, it returns to the regular interface automatically.

### On a slow or limited connection

You can skip the Nerd Font step (purely cosmetic) from inside the installer by unchecking it on the setup screen — no flag needed.

---

# Theme Selection

On the setup screen, pick a theme with a click (or arrow keys + Enter):

| Name | Description |
|------|-------------|
| MASU Minimal | Fast, clean, mobile-optimized (default) |
| MASU Cyber | Neon colors, icon-heavy |
| P10K Wizard | Launches the interactive p10k setup on first ZSH session |

---

# Fastfetch

You will also be asked whether you want fastfetch to show system info every time a terminal opens.

* If you choose **yes**, fastfetch runs automatically on each new terminal.
* If you choose **no**, fastfetch is installed silently. You can run it anytime with:

```
fastfetch-masu
```

To enable it on startup later, add this line to your `~/.zshrc`:

```
fastfetch --config ~/.config/fastfetch/config.jsonc
```

---

# What the Script Installs

* ZSH shell
* Oh My Zsh configuration framework
* Powerlevel10k theme
* ZSH Autosuggestions
* ZSH Syntax Highlighting
* ZSH Completions
* ZSH History Substring Search
* fzf (fuzzy finder with key bindings)
* fastfetch (system info display)
* MesloLGS NF (Nerd Font for P10K icons — skipped on Termux)

---

# Screenshots

### Hyprland / Kitty

More screenshots from other systems will be added soon.

---

# Project Structure

```
masu-terminal-installer
│
├── install.sh              # Launcher: sets up Python/venv, then runs masu_installer.py
├── install_core.sh         # The real install engine (called by masu_installer.py)
├── masu_installer.py       # Mouse-driven Textual installer UI
├── masu_installer.tcss     # Stylesheet for the Textual UI
├── requirements.txt        # Python deps (textual)
├── .gitignore
├── README.md
├── configs
│   ├── zsh
│   │   ├── p10k-termux.zsh     # Minimal Theme
│   │   └── p10k-cyber.zsh      # Cyber Theme
│   └── fastfetch
│       ├── mobile-config.jsonc  # Termux / Minimal
│       └── pc-config.jsonc      # Desktop
└── screenshots
    └── arch.png
```

`.masu-venv/` is also created here on first run (a private Python environment, gitignored, never committed).

---

# Why This Project Exists

Setting up a modern ZSH environment manually can take time, especially for new Linux users.

This project automates the entire setup process so anyone can install a professional terminal environment quickly.

---

# Changelog

### v10.0
* **`install.sh` is now a launcher, not the installer.** It no longer contains the old `fzf`/`whiptail` flow — instead it detects your OS, installs Python if needed, creates a private virtual environment (`.masu-venv/`, gitignored), installs `textual` into it, and hands off to `masu_installer.py`. The end result: `./install.sh` is still the only command anyone needs to run — no manual `pip install`, `python -m venv`, or activating anything.
* Sudo is now warmed up once, up front, in `install.sh` itself — before Python or the TUI even start — so there's only ever one password prompt, asked plainly in a normal terminal.
* Verified end-to-end on a completely clean slate (no system-wide `textual`, no existing venv): OS detection, Python setup, venv creation, package install, and handoff to the real TUI all confirmed working with real subprocess runs, not just code review.
* The old `install.sh` (fzf/whiptail flow) has been retired. If you relied on that specific interactive flow, `install_core.sh` still accepts the same `--theme=`/`--fastfetch=`/`--no-fonts` flags directly if you'd rather script around it yourself.

### v9.1
* **Critical fix:** `masu_installer.py` would get stuck at 0% with no way to type a sudo password — the prompt had nowhere visible to go since Textual takes over the whole screen. Fixed using Textual's `app.suspend()`: when sudo credentials aren't already cached, the TUI now genuinely hands control back to your real terminal first (with a real, typeable password prompt) before resuming and starting the actual install. Verified with a real pty and a real password typed in, not just code review.
* Added a hard timeout around the sudo warmup so it can never hang indefinitely in any environment, even ones where suspending the terminal isn't possible — it now fails safely with a clear message instead.
* `install_core.sh`'s own internal sudo handling is now purely a safety check (`sudo -n`, non-interactive) rather than attempting its own prompt, since the calling frontend is now always responsible for warming up credentials with a real terminal visible first.

### v9.0
* **Major architectural change:** the install engine was split out of `install.sh` into a new shared `install_core.sh`, accepting `--theme=`, `--fastfetch=`, `--no-fonts`, and `--yes` flags instead of showing interactive pickers. `install.sh` now wraps this engine with its existing `fzf`/`whiptail` interactive UI — same experience as before, no change needed if you're happy with the terminal-only flow.
* Added `masu_installer.py`, a new mouse-driven frontend built with [Textual](https://github.com/Textualize/textual): a sidebar-free but fully clickable wizard (Welcome → Theme/Extras → Confirm → Install → Finish) with real checkboxes, radio buttons, and a live progress bar, closer to a graphical installer while still running entirely in your terminal. It calls `install_core.sh` as a subprocess and streams its progress live — no install logic is duplicated between the two frontends.
* Verified end-to-end with real install runs (not mocked) through both `install.sh` and `masu_installer.py`, confirming identical results from either frontend.

### v8.6
* **Critical fix:** the new full-screen TUI gauge could hang indefinitely partway through installation on any system. Root cause was a classic bash gotcha — `((CURRENT_STEP++))` evaluates to the *old* value when counting up from zero, which `set -e` treats as a failure and kills the script silently. A second related bug in the shell-detection step (`command -v zsh` returning non-zero when zsh isn't yet installed) had the same effect. Both fixed; verified with a full clean install run that now completes end-to-end.
* The shell-setup step now explicitly handles "zsh isn't installed yet" instead of crashing — it warns and continues rather than failing the whole install.
* `sudo` calls that run after the gauge takes over the screen are now non-interactive (`sudo -n`), since a password prompt at that point would be invisible behind the gauge. Credentials are warmed up and kept alive in the background before the gauge starts, so this should never actually need a prompt — but if it ever did, it now fails fast and visibly in the log instead of hanging silently.

### v8.5
* Replaced the simple progress bar with a full-screen installer-style TUI using `whiptail`'s gauge widget — a proper boxed progress screen showing live percentage and the current step, closer to a real installer experience (`apt`/`pacman`-style). All the detailed [INFO]/[OK]/[WARN]/[FAIL] output now goes to a log file (`~/.masu-install.log`) shown at the end, since it would otherwise corrupt the full-screen gauge display. Falls back automatically to plain step text if `whiptail` isn't available or output isn't a real terminal.

### v8.4
* Fixed the installer appearing to hang/freeze on "Installing Nerd Font" on slow or restricted connections. Font downloads now have a hard connect/total timeout, and the step gives up immediately after the first failed connection instead of retrying all 4 font files individually. Fonts are purely cosmetic — the shell works fully without them.
* Added a `--no-fonts` flag to skip the font step entirely (`./install.sh --no-fonts`), useful on slow or data-limited connections.

### v8.3
* Theme and fastfetch prompts now use an interactive fzf picker (arrow keys + Enter) instead of typing a number. Falls back automatically to the old plain-text prompt if fzf isn't installed yet (e.g. very first run before dependencies are installed).

### v8.2
* Added automatic Nerd Font (MesloLGS NF) installation so P10K icons render correctly out of the box. Skipped on Termux.
* All `git clone` steps (oh-my-zsh, p10k, plugins) now retry up to 3 times with backoff on network failure instead of failing on the first hiccup — useful on slow or unstable connections.

### v8.1
* Fixed `plugin not found` warnings for zsh-autosuggestions, zsh-syntax-highlighting, and zsh-history-substring-search on re-runs. The installer now verifies each plugin's `.plugin.zsh` file (not just the folder) before skipping its clone, and `.zshrc` is written with only the plugins that actually installed successfully.

### v8.0
* BlackArch Edition — multi-distro support, theme selection, fastfetch opt-in/out.

---

# Future Improvements

* loading animations during cloning steps
* more theme presets
* support for additional distributions
* `--repair` mode to re-validate all components, not just plugins

---

# Contributing

Contributions are welcome.

If you want to improve the project:

1. Fork the repository
2. Create a new branch
3. Submit a pull request

---

# License

This project is open source and available under the MIT License.

---

# Author

Created by **Matyas Abraham**

masu-terminal-installer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README