Modshells: Modular Shell Configuration Manager

A declarative, idempotent configuration manager for modularising shell environments. Written in Ada for safety-critical reliability.

Deliverable

Modshells is a command-line tool that transforms monolithic shell configuration files into a modular, maintainable directory structure. The tool:

1. Creates a standardised directory hierarchy for shell configurations

2. Detects installed shells on your system (Bash, Zsh, Fish, Nushell, and 6 others)

3. Injects sourcing logic into shell configuration files (with backup)

4. Ensures idempotency - safe to run multiple times without side effects

Current Status

Aspect	Status
Directory creation	✓ Working
Shell detection	✓ Working (checks /usr/bin, /bin, /usr/local/bin, /opt/homebrew/bin)
Config backup	✓ Working (timestamped backups before modification)
Source injection	✓ Working (shell-specific syntax for all 10 shells)

Version 0.1 - Core functionality complete. The tool detects installed shells, backs up configs, and injects modular sourcing blocks.

What You Get

After running modshells, your shell configurations are organised into:

~/.config/nushell/modshells/
├── core/       # PATH, prompt, history, shell options
├── tools/      # git, fzf, starship, direnv configs
├── misc/       # Custom aliases and functions
├── os/         # Linux vs macOS differences
└── ui/         # Themes and visual settings

Each shell’s config file (.bashrc, .zshrc, etc.) sources these directories automatically. Add a new alias? Drop a file into misc/. OS-specific tweak? Put it in os/. Done.

The Problem

Traditional shell configuration becomes unwieldy:

• Single files grow to hundreds of lines

• Related configurations scattered throughout

• Difficult to share configurations across shells

• No clear separation of concerns

• Risky manual editing of critical dotfiles

The Solution

Modshells creates a standardised modular structure with shell-agnostic or shell-specific configuration snippets that are automatically sourced in order.

Features

Multi-Shell Support

Modshells detects and manages configurations for ten shells:

Shell	Status	Config File
Bash	✓ Supported	.bashrc
Zsh	✓ Supported	.zshrc
Fish	✓ Supported	config.fish
Nushell	✓ Primary	config.nu
Ion	✓ Supported	initrc
Oils (OSH/YSH)	✓ Supported	.oshrc
Tcsh	✓ Supported	.tcshrc
Ksh	✓ Supported	.kshrc
Dash	◐ Limited	ENV file
PowerShell	✓ Supported	profile.ps1

Idempotent Operations

All Modshells operations are idempotent:

• Running the tool multiple times produces the same result

• Existing configurations are never destroyed

• Automatic backup before any modification

• Signature-based detection of already-modularised shells

Safety-First Design

Built in Ada for maximum reliability:

• Strong static typing catches errors at compile time

• Exception handling ensures graceful failure

• No unsafe memory operations

• Deterministic behaviour

Architecture

Package Structure

src/
├── main/
│   └── modshells.adb          # Entry point
├── config_store/
│   ├── config_store.ads       # Configuration path interface
│   └── config_store.adb       # Environment & path resolution
└── shell_manager/
    ├── shell_manager.ads      # Shell operations interface
    └── shell_manager.adb      # Detection, creation, modularisation

Core Components

Config_Store

Resolves the modshells root path from MODSHELLS_CONFIG_PATH environment variable or defaults to ~/.config/nushell/modshells

Shell_Manager

Handles shell detection, directory creation, modularisation checking, and configuration injection

Signature-Based Idempotency

Modshells uses a signature comment to detect previously modularised configurations:

# MODSHELLS_START - DO NOT REMOVE THIS LINE
# ... sourcing logic ...
# MODSHELLS_END

This enables safe re-execution without duplicate injections.

Installation

Prerequisites

• GNAT (Ada compiler) - typically via gnat or gcc-ada package

• GPRBuild (GNAT project builder)

Building from Source

# Clone the repository
git clone https://github.com/hyperpolymath/modshells.git
cd modshells

# Build with GPRBuild
gprbuild -p -j0 modshells.gpr

# Binary is in bin/
./bin/modshells

Package Managers

# Guix (primary)
guix install modshells

# Nix (alternative)
nix profile install github:hyperpolymath/modshells

Usage

Basic Usage

# Build and run
gprbuild -p -j0 modshells.gpr
./bin/modshells

Example output:

=== Modshells v0.1 ===
Configuration path: /home/user/.config/nushell/modshells

Creating modular directory structure...
  Directories ready: core, tools, misc, os, ui

Detecting installed shells...
  bash: [installed]
  dash: [not found]
  fish: [installed]
  ion: [not found]
  nushell: [installed]
  tcsh: [not found]
  zsh: [installed]
  oils: [not found]
  pwsh: [not found]
  ksh: [not found]

Modularising shell configurations...
Modularising bash...
  Backup created: /home/user/.bashrc.modshells-backup-20250101-120000
  Injected modshells sourcing block.
Modularising fish...
  Injected modshells sourcing block.
...

=== Modshells complete ===

Custom Configuration Path

# Use custom configuration path
export MODSHELLS_CONFIG_PATH="$HOME/.config/shells/modular"
modshells

# Target specific shells only
modshells init --shell=bash,zsh

Populating Your Configuration

After initialisation, add configuration snippets:

# Add a tool configuration
echo 'alias g="git"' > ~/.config/nushell/modshells/tools/git.sh

# Add OS-specific config
echo 'export BROWSER=firefox' > ~/.config/nushell/modshells/os/linux.sh

Files are sourced alphabetically. Use numeric prefixes for ordering:

core/
├── 00-path.sh
├── 10-prompt.sh
└── 20-history.sh

Configuration

Environment Variables

MODSHELLS_CONFIG_PATH

Override default configuration root directory. Default: ~/.config/nushell/modshells

Modular Categories

Directory	Purpose
core/	Essential shell settings: PATH modifications, prompt configuration, history settings, shell options
tools/	Tool integrations: git aliases, fzf configuration, starship prompt, direnv, asdf
misc/	General aliases, utility functions, one-off customisations
os/	OS-specific configurations: Linux vs macOS differences, distro-specific settings
ui/	Visual customisations: colours, themes, terminal-specific settings

Examples

The examples/ directory contains ready-to-use configuration snippets:

# Copy all examples to your modshells directory
cp -r examples/* ~/.config/nushell/modshells/

# Or copy individual files
cp examples/tools/git.sh ~/.config/nushell/modshells/tools/
cp examples/misc/aliases.sh ~/.config/nushell/modshells/misc/

Available Examples

File	Description
core/00-path.sh	PATH modifications for ~/.local/bin, Cargo, Go, Deno
core/10-history.sh	History size, deduplication, timestamps, ignore patterns
core/20-options.sh	Shell options (extglob, cdspell, globstar), editor, locale
tools/git.sh	Git aliases (gs, ga, gc, gp, gl, glog, etc.)
tools/fzf.sh	Fuzzy finder setup with fd integration
tools/starship.sh	Starship prompt initialisation
misc/aliases.sh	Navigation (.., …​), ls variants, safety nets (rm -i)
misc/functions.sh	Utility functions: mkcd, extract, ff, fd, backup
os/linux.sh	Package manager aliases, systemd shortcuts
os/macos.sh	Homebrew setup, macOS-specific utilities
ui/colours.sh	Terminal colours, GCC colours, man page colours
ui/prompt.sh	Custom bash prompt with git branch (fallback for non-starship)

Testing

Smoke Test

Run the shell-based smoke test to verify the build:

# From the repository root
./tests/smoke_test.sh

The smoke test verifies:

• Source files exist

• Examples have correct structure

• SPDX license headers present

• Binary runs (if built)

• Directory creation works

• Idempotency check passes

Unit Tests

Build and run the Ada unit tests:

# Build tests
gprbuild -p -j0 -P tests/tests.gpr

# Run tests
./bin/test_shell_manager

Development Status

Current version: v0.1

Implemented Features

Feature	Description
Directory creation	Idempotently creates core/, tools/, misc/, os/, ui/ structure
Path resolution	Reads MODSHELLS_CONFIG_PATH or defaults to ~/.config/nushell/modshells
Shell detection	Checks /usr/bin, /bin, /usr/local/bin, /opt/homebrew/bin for shell binaries
Config file backup	Creates timestamped backups (.modshells-backup-YYYYMMDD-HHMMSS) before modification
Source injection	Appends shell-specific sourcing blocks with MODSHELLS_START/END markers
Shell-specific syntax	Generates correct sourcing code for all 10 shells (POSIX, Fish, Nushell, Tcsh, Ion, PowerShell)
Idempotency	Signature-based detection prevents duplicate injections
Build system	GPRBuild project files with CI/CD (GitHub Actions)

Future Enhancements

See ROADMAP.adoc for planned features including:

• Command-line arguments (--shell=bash,zsh, --dry-run)

• Shell-agnostic .modshells config format

• Configuration drift detection

• Snippet management commands

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

This project follows the Rhodium Standard Repository (RSR) conventions.

Language Policy

This project adheres to the Hyperpolymath Standard:

• Ada for core application logic

• Nushell for automation scripts

• Bash/POSIX for git hooks only

See .claude/CLAUDE.md for complete language policy.

License

SPDX-License-Identifier: AGPL-3.0-or-later OR MIT

Dual-licensed under GNU Affero General Public License v3.0 or later, or Palimpsest-MPL-1.0 License. See LICENSE.txt for details.

Citation

For academic use, see CITATIONS.adoc for BibTeX, Harvard, OSCOLA, MLA, and APA 7 formats.