myshell

myshell is a Bash-first hybrid framework for building, bootstrapping, and operating a modular user environment.

It treats the shell runtime as the technical base, then layers optional profiles and operational modules on top of it. The result is a structured system that aims for two main properties:

• modularity: each component has a clear layer, a concrete purpose, and explicit activation
• reproducibility: the managed local environment and its modular composition can be reproduced consistently

myshell is not intended to look like a classic dotfiles repository, a loose collection of personal scripts, a simple .bashrc bootstrap, or a package manager. It is meant to behave like a lightweight, Bash-based framework for managing a stable user environment and exposing reusable operational tooling.

Scope

myshell is designed to:

• bootstrap a Bash-based user environment
• manage shell runtime behavior through a structured core
• load optional profiles explicitly
• expose operational modules through a stable framework structure
• integrate official external companion repositories such as config_files

myshell is not designed to:

• manage arbitrary local state outside its declared managed components
• behave like a package manager
• present itself as a generic framework without a concrete user-environment use case

Core model

myshell is organized around the following layers:

Core

The core is the runtime base of the framework. It provides the shell entrypoints and the structure through which the rest of the system is loaded.

This includes:

• .bash_profile
• .bashrc
• aliases
• functions
• jobs

Profiles

Profiles are optional environment components loaded from core/shells/bash/profiles/.

Profiles are part of the framework core model. They are used for shell environment setup, bootstrap behavior, and managed configuration deployment.

Profile are opt-in through explicit loader blocks in `.bashrc`.

### Modules

Modules are operational tooling components. They expose commands and workflows on top of the stable user-environment base provided by the framework.

Modules are part of the core identity of myshell, not an afterthought.

Optional components

PowerShell support exists as an optional layer. It is supported, but it is not part of the primary identity of the framework.

Official external companion repositories

myshell supports official companion repositories that are external in storage but functionally part of the framework ecosystem.

The primary companion repository is:

• config_files

config_files is not treated as a secondary integration. It is the official companion repository for managed external configuration consumed by myshell.

Managed vs unmanaged behavior

A core principle of myshell is explicit control.

When a component is active and managed by the framework, the framework is authoritative for that component.

When a component is disabled, it stops being managed.

This means:

• active managed components are expected to follow framework-defined behavior
• disabled components are outside the authority of the framework
• activation state is explicit and visible through the corresponding loader blocks

Stability model

myshell aims to keep both of these stable:

• the structure of the framework
• the experience of use

What may vary:

• which profiles and modules are enabled
• which components are sourced from the official companion repository
• future official external integrations in the myshell ecosystem

Activation model

The framework is designed around explicit, visible activation.

The expected user experience is:

• load a predefined environment
• enable or disable explicit pieces of that environment
• use operational modules on top of a stable base

This is an opt-in modular system, not a hidden auto-magic bootstrap.

Why Bash-first matters

myshell is Bash-first by design.

Bash is not just the implementation language; it is part of the framework identity. The framework is intended to stay technically direct, operational, and readable while still being powerful.

The target is power within visible simplicity:

• the internal system can grow
• but the user model and framework structure should remain understandable and explicit

Repository structure

Current top-level structure relevant to the framework model:

• core/
  • framework runtime and shell entrypoints
• core/shells/bash/profiles/
  • optional managed environment components
• core/shells/bash/.bash_profile
  • framework entrypoint
• core/shells/bash/.bashrc
  • explicit activation surface for profiles
• modules/
  • operational toolkit components
• core/shells/pwsh/
  • optional PowerShell support

Installation

Bash

1. Back up your current $HOME/.bash_profile if needed.
2. Clone the repository.
3. Copy the framework entrypoint to your home.
4. Set project_path.
5. Reload the shell session.

git clone git@github.com:e-lemongrab/myshell.git
cp -rfv myshell/core/shells/bash/.bash_profile "$HOME"
sed -i 's|$HOME/Documents/myshell|'"$(pwd)"'/myshell|g' "$HOME/.bash_profile"
exec -l "$SHELL"

After that:

• run checks to list compatibility information
• run myshell to view available commands

PowerShell

Once the Bash configuration is active, and if pwsh is installed, myshell can also set the PowerShell profile at:

• ~/.config/powershell/Microsoft.PowerShell_profile.ps1

If you want to use the PowerShell profile from Windows:

1. Install a WSL2 distribution.
2. Edit $PROFILE with the content from core/shells/pwsh/Microsoft.PowerShell_profile.ps1.
3. Set the required values in the VARIABLE DECLARATION section.

Profiles and modules

myshell loads optional Bash components from core/shells/bash/profiles/ through explicit blocks in core/shells/bash/.bashrc.

Profiles currently loaded by default blocks in .bashrc

Examples include:

• .git-configs
• .appearance
• .completion
• .history
• .path
• .pwsh
• .software
• .config_files
• .ssh

Companion repository: config_files

config_files is the official companion repository of myshell.

Within the framework model:

• myshell is the framework and orchestration layer
• config_files is the managed external source of truth for supported configuration artifacts

This relationship is part of the intended architecture of the framework.

Extension model

myshell is modular, but that modularity is structured.

In practice, new functionality should fit one of the framework layers:

• core runtime behavior
• profile
• service
• module
• official external companion integration

If a new component does not clearly fit one of those layers, it should not be added until its role is defined.

Summary

myshell should be understood as:

• a Bash-first hybrid framework
• a structured user-environment manager
• a modular shell and services system
• a reproducible local environment framework
• a lightweight operational platform built on top of Bash