A modern, AI-powered zsh environment for macOS and iTerm2
Fast startup Β· smart navigation Β· AI assistance Β· auto-updating
| Feature | Description | |
|---|---|---|
| π€ | AI integration | Chat, command suggestions, and commit messages via a local LLM |
| π | Starship prompt | Fast prompt showing directory, git branch, git status, and command duration |
| π | Smart navigation | Zoxide learns your habits and jumps anywhere instantly |
| π | Fuzzy everything | fzf-powered file search, git branches, history, and diffs |
| π― | Project detection | Configures PATH and shows make targets when you cd into a project |
| π | Auto-updater | Weekly update checks with one-key confirmation |
| π§© | Plugin management | Lightweight manifest-based zsh plugins, no framework needed |
| π¨ | Modern CLI tools | eza, bat, dust, delta, and prettyping replace legacy tools |
git clone https://github.com/moarpheus/mshell ~/.mshell && ~/.mshell/installThat's it. The install script handles everything:
- installs Homebrew if missing
- installs all CLI tools via
brew bundle - clones zsh plugins
- symlinks configs (starship, aichat, gitconfig, gitignore)
- appends the source line to
~/.zshrc(idempotent, safe to re-run)
| Shortcut | Action |
|---|---|
Ctrl+B |
Backward word |
Ctrl+F |
Forward word |
β |
History substring search up |
β |
History substring search down |
History search is contextual: type part of a command, then use the arrows to find matching history entries.
fzf is active in file search, git operations, and anywhere you see the βΌ prompt. These shortcuts work inside an fzf session, for example after Ctrl+T, Ctrl+R, or any fzf-powered command:
| Shortcut | Action |
|---|---|
? |
Toggle preview panel |
Shift+Down |
Scroll preview down |
Shift+Up |
Scroll preview up |
PgDn |
Preview page down |
PgUp |
Preview page up |
Ctrl+A |
Select all results |
Ctrl+Y |
Copy selection to clipboard |
Ctrl+E |
Open selection in the editor |
These keys are fzf-internal bindings. They work only inside an fzf picker, not at the regular shell prompt.
All AI features use aichat connected to a local LLM server (LM Studio or mlx-lm-server at localhost:1234).
| Command | Description | Example |
|---|---|---|
ai |
Chat with your local LLM | ai "explain this error message" |
how |
Get a shell command suggestion, with optional execution | how "find files larger than 100MB" |
gai |
Generate a commit message from staged changes | git add -A && gai |
hsearch |
Search shell history by description | hsearch "docker compose restart" |
$ git add -A
$ gai
Suggested commit message:
feat: add user authentication middleware
Use this message? [y/n] y
[main abc1234] feat: add user authentication middleware
$ how "list all listening ports"
> lsof -iTCP -sTCP:LISTEN -n -P
Execute? [y/n]
AI functions need a local LLM server running. Start LM Studio or mlx-lm-server before use.
When you cd into a project directory, mshell automatically:
| Marker file | Action |
|---|---|
package.json |
Prepends node_modules/.bin to PATH |
Makefile |
Displays up to 20 available make targets, once per session |
PATH is cleaned up when you leave the directory, so there are no stale entries.
Every 7 days, mshell checks for upstream updates on shell startup:
- Fetches from origin with a 2-second timeout, so it never blocks your shell.
- Prompts
y/nto update if new commits exist. - Updates via
git pull --rebaseon confirmation. - Skips silently on decline or network failure.
yazi is a fast terminal file manager with previews. Run y to open it in the current directory. When you quit with q, your shell changes to the directory you ended up in; quit with Q to stay where you started.
| Key | Action |
|---|---|
h j k l |
Move left, down, up, right (into or out of directories) |
Enter |
Open the selected file |
Space |
Select or deselect a file |
y x p |
Yank (copy), cut, paste |
d D |
Move to trash, delete permanently |
a r |
Create a file or directory, rename |
/ n N |
Search, next match, previous match |
. |
Toggle hidden files |
q Q |
Quit (cd to current dir), quit (stay put) |
Previews cover images, video thumbnails (ffmpeg), PDFs (poppler), archives (7-Zip), and JSON (jq). Press ~ inside yazi for the full key list.
| Alias | Expands to |
|---|---|
g |
git |
lg |
lazygit (git TUI) |
ga |
git add |
gc |
git commit |
gc-m |
git commit -m |
gl |
git log (pretty graph) |
gai |
AI-generated commit message |
cdr |
cd to the git repository root |
| Alias | Action |
|---|---|
g a |
add |
g c |
commit |
g co |
checkout |
g n <name> |
create a new branch |
g l |
pretty log graph |
g s |
status (short, with branch) |
g yolo |
commit with --no-verify |
lazygit is a full-screen terminal UI for git. Run lg inside any repository to stage, commit, branch, rebase, and stash without typing individual git commands.
| Key | Action |
|---|---|
? |
Show all keybindings for the current panel |
Tab |
Cycle between panels |
Space |
Stage or unstage the selected file, or pop a stash |
a |
Stage or unstage everything |
c |
Commit staged changes |
P |
Push |
p |
Pull |
q |
Quit |
For line-by-line staging, press Enter on a file in the Files panel, then Space on individual lines. Press ? any time to see the full key list for the panel you are in.
| Legacy tool | Modern replacement | Why |
|---|---|---|
ls |
eza | Colours, icons, git status, tree view |
cat |
bat | Syntax highlighting, line numbers, git diff |
cd |
zoxide | Frecency-based smart jumping |
ncdu |
dust | Fast, visual disk usage |
df |
duf | Clear per-mount disk free output |
ping |
prettyping | Graphical ping output |
diff (git) |
delta | Syntax-highlighted, side-by-side diffs |
top |
btop | Resource monitor |
| Pure prompt | Starship | Fast, customizable, cross-shell prompt |
| Alias | Command |
|---|---|
d |
docker |
dc |
docker-compose |
dsh <container> |
Attach a shell to a container |
dbr |
Build and run the current Dockerfile |
dcrc <service> |
Rebuild and restart a compose service |
dcl <service> |
Tail compose logs |
| Alias | Command |
|---|---|
v |
nvim (falls back to vim) |
y |
yazi file manager (cd's to where you quit) |
cat |
bat |
df |
duf |
ping |
prettyping |
ls |
eza --color=always --group-directories-first |
cd |
z (zoxide) |
tf |
terraform |
mt |
make test |
| Alias | Action |
|---|---|
up-vim |
Pull the latest nvim config |
up-shell |
Pull the latest mshell config |
up-all |
Update both the vim and shell configs |
update_plugins |
Update all zsh plugins from the manifest |
The prompt shows directory, then git branch, then git status, then command duration.
To customise it, edit ~/.mshell/starship.toml (symlinked to ~/.config/starship.toml). See the Starship docs for all options.
Configured to connect to a local OpenAI-compatible API:
model: local:qwen2.5-coder-7b-instruct-mlx
clients:
- type: openai-compatible
name: local
api_base: http://localhost:1234/v1Models available: qwen2.5-coder-7b-instruct-mlx, google/gemma-4-26b-a4b-qat, qwen/qwen3.6-27b.
Edit ~/.mshell/aichat_config.yaml to change models or the API endpoint.
Default search uses ripgrep for speed, respects .gitignore, and shows bat-powered previews. Configuration lives in the env file.
Plugins are listed in plugins.txt, one git URL per line:
https://github.com/zsh-users/zsh-completions.git
https://github.com/zsh-users/zsh-syntax-highlighting.git
https://github.com/zsh-users/zsh-history-substring-search.git
https://github.com/zsh-users/zsh-autosuggestions.git
The plugins give you richer completions, red/green syntax highlighting as you type, history search with the arrow keys, and greyed-out autosuggestions from history (accept with the right-arrow).
| Command | Action |
|---|---|
./install |
Clones any missing plugins |
update_plugins |
Pulls the latest for all plugins |
To add a plugin, append its git URL to plugins.txt and run ./install.
Versioning is automated with semantic-release. On every push to main, a GitHub Actions workflow reads the commit messages, works out the next version, creates a git tag and GitHub Release, and commits an updated CHANGELOG.md.
Commit messages follow Conventional Commits:
fix:triggers a patch releasefeat:triggers a minor releasefeat!:or aBREAKING CHANGE:footer triggers a major release- other types such as
chore:,docs:, andci:do not trigger a release
The workflow lives in .github/workflows/release.yml and its config in .releaserc.json. It authenticates with the CI_TOKEN repository secret.
- add your own aliases: create
~/.mshell/localand source it from~/.zshrcafter mshell - change the prompt: edit
starship.toml, where modules are toggled withdisabled = trueorfalse - switch the AI model: edit
aichat_config.yamland change themodel:field - add a plugin: append the git URL to
plugins.txtand run./install - iTerm2 colours: import any
.itermcolorsfile from theiterm2/directory
~/.mshell/
βββ install # Bootstrap script, run once or re-run safely
βββ custom # Entry point sourced by ~/.zshrc
βββ env # Environment variables, PATH, fzf config
βββ aliases # Shell aliases
βββ functions # Shell functions (gai, how, hsearch, and more)
βββ gitconfig # Git aliases and configuration
βββ starship.toml # Prompt configuration
βββ aichat_config.yaml # AI tool configuration
βββ plugins.txt # Plugin manifest
βββ Brewfile # Homebrew dependencies
βββ zsh/
β βββ custom # Zsh setup, keybindings, completions
β βββ auto_updater.zsh # Weekly update checker
β βββ project_detector.zsh # chpwd hook for project detection
β βββ plugins/ # Cloned zsh plugins
βββ iterm2/ # iTerm2 colour schemes
βββ working/ # Runtime state (history, zoxide data, update timestamps)
Built for macOS, zsh, and iTerm2