synth-shell: a bag of bash scripts you bolt onto your .bashrc

A collection of scripts, not a shell framework

The README makes the scope explicit in its first paragraph. synth-shell "is not a single tool, but a collection of scripts and aliases", and it invites you to install only the ones you want. Everything is written in bash, and the project describes itself as boosting your terminal script by script.

That framing is the whole design decision. There is no framework to adopt, no mandatory configuration format, no prompt engine to configure. Each script is standalone, and the setup script asks you which ones you want.

The package covers three broad areas. There is a system status report that runs on every new session and prints things like external IP address and CPU temperature, plus a fancy bash prompt with colours, triangular separators and git branch status, plus a set of everyday conveniences: a better ls, and colourised aliases for grep, pacman, tree, dmesg and free, an autocompleting sudo, and a history alias that drops consecutive duplicate commands.

For a system administrator who wants one better command, that granularity is the appeal. For someone who wants their shell configuration reproducible across twenty machines, the same granularity becomes the cost.

Two headline features live in separate repositories

The usage list links out for the two pieces that matter most, and this is the single most important structural fact in the repository.

The status report is the synth-shell-greeter project, and the fancy bash prompt is the synth-shell-prompt project. Both are separate GitHub repositories, and the README tells you to clone this repository recursively because there are git submodules in it. The .gitmodules file at the repository root and the synth-shell/ and bash-tools/ directories reflect that layout.

The consequence is concrete: a plain clone leaves you without the two components most people want, and a recursive clone fetches code whose version this repository does not fully control. When something breaks in the prompt or the greeter, you are looking at two codebases, and the fixes may live in the other repositories rather than here.

It also explains why the release tags here are old. The v2.4 release was published on 2020-01-23, with 2.3 in January 2020 and v2.2 in December 2019. The last push to this repository was on 2026-08-22, so work continues, but the tagged releases of the bundle itself are from 2020.

The setup script asks for install and user

Installation is a clone plus an interactive script. The README asks for a recursive clone because of the submodules, then running setup.sh, then choosing install and user at the prompts, then opening a new terminal.

git clone --recursive https://github.com/andresgongora/synth-shell.git
cd synth-shell
./setup.sh

The installation details section gives a slightly longer version that makes the script executable first, and points to a video walkthrough.

git clone --recursive https://github.com/andresgongora/synth-shell.git
chmod +x synth-shell/setup.sh
cd synth-shell
./setup.sh

The setup script guides you step by step and lets you choose what to install. The two meaningful choices are the scope, user only or system-wide, and the system-wide path requiring superuser privileges. The README recommends the user install.

Because the scripts are called from your .bashrc file, the change to your shell environment is not a file you drop in, it is a line the installer appends. That matters when you want to remove it later, and when you want to know what a colleague's shell is doing when they say it "works". The README does not document an uninstall procedure, so plan on reading your .bashrc and removing the added lines yourself.

Powerline fonts and a UTF-8 locale are hard prerequisites

The README lists the requirements before the install steps, and two of them bite. First, powerline fonts, installed as powerline-fonts on Arch or fonts-powerline on Ubuntu, because the prompt's triangular separators need a font that can draw them.

sudo pacman -S powerline-fonts

sudo apt install fonts-powerline

Second, a terminal font. The README recommends hack-ttf, available under that name for most distros.

The failure mode worth knowing about in advance is the triangle separator not appearing even with the fonts installed. The README attributes this to a non UTF-8 locale and tells you to edit /etc/locale.conf to select your language in UTF-8 format and run sudo locale-gen. If that does not help, the suggestion is to try a different font, since some fonts lack the special characters.

The README also states plainly that support for Windows is not guaranteed, and invites contributions for bugs on that platform.

status.config and where the thresholds live

The status report is the piece with the most configuration surface. It runs on every new terminal session, local or SSH, and if it detects that a system parameter such as CPU load or memory is over a critical threshold, it prints a warning along with additional information about the cause. It also monitors servers, Raspberry Pis and workstations, and it prints an ASCII logo, either your own or your distribution's.

The configuration lives in a file whose path depends on the install scope: ~/.config/synth-shell/status.config for a user-only install, and /etc/synth-shell/status.config for a system-wide one. The README also points to example files in the same directory that you can copy over the defaults.

The design is sensible for a shared server where the system-wide config holds the thresholds, but it creates a divergence between accounts on the same machine. A user install ignores the system config entirely, so two people logging into the same host can see different warnings for the same CPU load. Anyone deploying this should decide which of the two files is the source of truth.

The bash prompt reports git state through a fourth separator

fancy-bash-prompt.sh adds colour and triangular separators to the prompt, and when the current working directory is inside a git repository it also shows the branch. The README describes the git status as a fourth separator carrying the name of the current branch plus an icon indicating the state of the repository, and that icon can be changed in the config.

The README also states the prompt shows git statuses such as whether the repository needs a pull or push, or is dirty, when you are in a directory that is part of a git repository. The prompt tool itself is the synth-shell-prompt repository, so its full option set lives outside this one.

The mechanism has a cost that is worth stating plainly: the prompt has to run git commands on every prompt render to know the repository state. On a large repository or a slow filesystem that is a noticeable pause before every command. The visual gain and the per-command cost are the trade being made, and it is a trade the project makes for you by default.

Licensing, configuration layout and a stale release tag

The licence is GPL-3.0, with the text in the LICENSE file and the README pointing there. For scripts that are copied into your home directory and sourced from your .bashrc, GPL-3.0 is a real consideration for a company that ships an image to staff, and the distinction between running a tool and distributing a modified copy is where a legal review would matter.

The repository layout is worth noting: setup.sh at the root, bash-tools/ for the extra commands, config_templates/ for the shipped defaults, doc/ for images and documentation, synth-shell/ for the submodules, plus tests/ and an AUTHORS.md. The presence of config_templates/ is how the default status config reaches a fresh install.

On upkeep, the last push was on 2026-08-22, so work is happening, but the most recent tagged release is v2.4 from 2020-01-23. If you are pinning a version for reproducibility, you are pinning something six years old whose two main components come from separate repositories at whatever state a recursive clone resolves to. Read the .gitmodules file before you pin anything.

Editorial conclusion

synth-shell is a good fit for someone on a Linux workstation or a managed server who wants a readable system summary and a nicer prompt without adopting a full shell framework, and the per-user install keeps the footprint inside your own home directory. It is the wrong tool if you want a deterministic, versioned shell configuration across a fleet, since the pieces come from separate repositories resolved as submodules, and it is the wrong tool on Windows, where the README says support is not guaranteed. Before running setup.sh, decide whether you want the user install or the system-wide one, because the config paths differ: ~/.config/synth-shell/status.config for a user install and /etc/synth-shell/status.config for a system-wide install.

Frequently asked questions

Official sources

1. andresgongora/synth-shell on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases