neoshell - A Zsh-like Lua Shell

A powerful Unix-like shell written entirely in Lua with zsh-inspired features, Catppuccin Mocha theming, and modern shell capabilities.

Note

this shell will be later added to neovim config by @ijadux2 in plugins branch sharingan.nvim

Features

Zsh-like Experience

• Zsh-style Prompt - Customizable with escape sequences (%n, %m, %~, %g)
• Git Integration - Automatic git branch, dirty status, and ahead/behind indicators
• Right Prompt (RPROMPT) - Display time or other info on the right
• Zsh Globbing - Support for **/*.lua recursive patterns
• Word Modifiers - %:h, %:t, %:r, %:e, %:p modifiers
• Global Aliases - Expand anywhere in command (e.g., G = "| grep")

Modern Shell Features

• Syntax Highlighting - Color commands/arguments as you type
• Auto-suggestions - Greyed-out suggestions from history
• Fuzzy Tab Completion - Fzf-style completion matching
• Auto-cd - Type directory name to cd into it
• Directory Stack - pushd/popd/dirs support
• Job Control - Background jobs with fg/bg
• History Expansion - !, !!, !pattern, !n
• Better Error Messages - Suggests corrections for typos

Environment Management

• Enhanced export - Like zsh, lists sorted variables with colors
• path command - Manage PATH easily (path add, path remove)
• Variable Expansion - $VAR, ${VAR} with shell and environment variables
• Command Substitution - $(cmd) and backticks
• Arithmetic Expansion - $((expr))

UI Features

• Catppuccin Mocha Theme - Beautiful color scheme
• Tab Completion - Commands, aliases, and file paths
• Colored Output - Syntax highlighting for better readability
• TUI App Support - Works with vim, nvim, less, htop, etc.

Requirements

• Lua 5.1 or later
• Optional: luajit (for better performance)
• Optional: luafilesystem (lfs) - for native directory handling
• Optional: linenoise - for tab completion support

Installing Dependencies

# Install linenoise for tab completion
luarocks --local install linenoise

# Install luafilesystem for better cd support (optional)
luarocks --local install luafilesystem

Installation

1. Clone or download this repository
2. Copy the example config file to your home directory:

   cp .shell.toml ~/.shell.toml  # or use .shell.yaml, .shell.conf, etc.

3. Make the script executable:

   chmod +x neoshell.lua

Usage

Run the shell:

./neoshell.lua
# or
lua neoshell.lua

Configuration

Neoshell supports multiple configuration file formats (checked in order):

1. ~/.shell.toml - TOML format (recommended)
2. ~/.shell.yaml or ~/.shell.yml - YAML format
3. ~/.shell.json - JSON format
4. ~/.shell.conf or ~/.shellrc - INI format
5. ~/.neoshell - Original Lua format (backward compatible)

TOML Example (~/.shell.toml)

# Prompt configuration
prompt = "%n@%m %~ %g$ "
rprompt = "%t"  # Right prompt showing time

# Theme settings
colors = true

[theme]
base = "#b4befe"

# Syntax highlighting colors
[syntax_colors]
command = "green"
argument = "text"
string = "yellow"
variable = "pink"
comment = "overlay0"
error = "red"
suggestion = "overlay0"

# Feature toggles
syntax_highlighting = true
auto_suggestions = true
fuzzy_completion = true
auto_cd = true

# Shell options
history_file = "~/.neoshell_history"
history_size = 500

# CD search path
cdpath = [".", "..", "~"]

# Aliases
[aliases]
ll = "ls -la"
la = "ls -a"
l = "ls -l"
home = "cd ~"
back = "cd -"
gs = "git status"
ga = "git add"
gc = "git commit"
gp = "git push"

# Global aliases (expand anywhere in command)
[global_aliases]
G = "| grep"
L = "| less"
H = "| head"
T = "| tail"

YAML Example (~/.shell.yaml)

prompt: "%n@%m %~ %g$ "
rprompt: "%t"
colors: true

aliases:
  ll: "ls -la"
  la: "ls -a"
  gs: "git status"

global_aliases:
  G: "| grep"
  L: "| less"

syntax_highlighting: true
auto_suggestions: true
fuzzy_completion: true
auto_cd: true

INI Example (~/.shell.conf)

prompt = %n@%m %~ %g$
rprompt = %t
colors = true
syntax_highlighting = true
auto_suggestions = true

[aliases]
ll = ls -la
la = ls -a
gs = git status

[global_aliases]
G = | grep
L = | less

[theme]
base = #b4befe

[syntax_colors]
command = green
argument = text
variable = pink

Prompt Escape Sequences

Sequence	Description
%%n	Username
%%m	Hostname (machine)
%%~	Current directory (shortened, shows ~ for home)
%%g	Git branch (if in git repo)
%%t	Current time (HH:MM)
%%#	# for root, $ for user
%%%	Literal percent sign

Built-in Commands

• cd [dir] - Change directory (supports ~, -, auto-cd)
• pwd - Print working directory
• pushd [dir] - Push directory to stack and cd
• popd - Pop directory from stack
• dirs - Display directory stack
• exit [n] - Exit shell with optional exit code
• echo [args] - Print arguments
• printf [fmt] - Printf-like output
• test [expr] - Test expression
• export [var[=val]] - Set/display environment variables
• alias [name=cmd] - Define/list aliases
• unalias [name] - Remove alias
• path - Display PATH directories
• path add /dir - Add directory to PATH
• path remove /dir - Remove directory from PATH
• source [file] - Execute commands from file
• set [var=val] - Set/list shell variables
• unset [var] - Unset shell variable
• type [cmd] - Show command type
• jobs - List background jobs
• fg [job] - Bring job to foreground
• bg [job] - Resume job in background
• help - Show help message

Advanced Features

Syntax Highlighting

Commands and arguments are highlighted in real-time as you type:

• Commands - Green
• Arguments - Default text color
• Strings - Yellow
• Variables - Pink
• Errors - Red

Auto-suggestions

Type a few characters and see grey suggestions from your history. Accept with right arrow or End key.

Fuzzy Completion

Tab completion uses fuzzy matching:

• vim matches nvim, vimdiff, gvim
• gc matches git commit, git checkout

Zsh-style Globbing

• *.txt - Match all .txt files
• **/*.lua - Recursively find all .lua files
• src/**/test_*.py - Find test files in any subdirectory

Word Modifiers

After history expansion or variable expansion:

• %:h - Head (directory part)
• %:t - Tail (filename only)
• %:r - Remove extension
• %:e - Extension only
• %:p - Full path

History Expansion

• !! - Last command
• !n - Command number n
• !pattern - Last command starting with pattern
• !$ - Last argument

Example Session

jadu@localhost ~ (main)* $ ls
neoshell.lua  .shell.toml  README.md
jadu@localhost ~ (main)* $ cd src
jadu@localhost ~/src (main)* $ vim
[opens vim...]
jadu@localhost ~/src (main)* $ gs
On branch main
Your branch is ahead of 'origin/main' by 2 commits.
Changes not staged for commit:
  modified:   neoshell.lua
jadu@localhost ~/src (main)*↑2* $ path add ~/.local/bin
1 /home/jadu/.local/bin
2 /usr/local/bin
...
jadu@localhost ~/src (main)*↑2* $ export EDITOR=vim
export EDITOR="vim"
jadu@localhost ~/src (main)*↑2* $ !!
export EDITOR="vim"
jadu@localhost ~/src (main)*↑2* $ echo $EDITOR
vim
jadu@localhost ~/src (main)*↑2* $ ls **/*.lua
neoshell.lua  test/test_helper.lua
jadu@localhost ~/src (main)*↑2* $ echo %:h
/home/jadu/src
jadu@localhost ~/src (main)*↑2* $ exit

License

MIT License