A Modern, POSIX-compatible, Generative Shell.

This project is in early development stage. Use at your own risk! Please expect bugs, incomplete features and breaking changes.

That said, if you can try it out and provide feedback, that would help make gsh more useful!

• POSIX-compatibility: you shouldn't need to learn a new shell language to adopt gsh
• Embrace AI: gsh is designed from the ground up for the generative AI era to provide you with intelligent assistance at the right place, right time
• Privacy: gsh should allow you to use local LLMs for guaranteed privacy
• Customizability: gsh is your shell. You should be able to configure it to your liking
• Extensibility: gsh should allow the community to build and share extensions to make it more useful

gsh will automatically suggest the next command you are likely want to run.

gsh will provide an explanation of the command you are about to run.

See the complete guide: docs/AGENT.md

gsh can run with either

• Local LLMs through Ollama
• Or remote LLMs through an OpenAI API-compatible endpoint, such as OpenRouter

To install gsh:

# Linux and macOS through Homebrew
brew tap atinylittleshell/gsh https://github.com/atinylittleshell/gsh
brew install atinylittleshell/gsh/gsh

# You can use gsh on arch, btw
yay -S gsh-bin

Windows is not supported (yet).

gsh can automatically detect newer versions and self update.

To build gsh from source, ensure you have Go installed and run the following command:

make build

This will compile the project and place the binary in the ./bin directory.

gsh can be configured through a configuration file located at ~/.gshrc. Configuration options and default values can be found in .gshrc.default.

gsh also loads a ~/.gshenv file, right after loading ~/.gshrc. This file can be used to set environment variables that the gsh session will use.

When launched as a login shell (gsh -l), gsh will also load /etc/profile and ~/.gsh_profile at start (before ~/.gshrc).

You can use Starship.rs to render a custom command line prompt. See .gshrc.starship for an example configuration.

You can manually start gsh from an existing shell:

gsh

You can also automatically launch gsh from another shell's configuration file:

# For bash
echo "gsh" | tee -a ~/.bashrc

# For zsh
echo "gsh" | tee -a ~/.zshrc

# Your zsh config may have set "gsh" as an alias for `git show`.
# In that case, you would need to use the full path to gsh.
echo "/full/path/to/gsh" | tee -a ~/.zshrc

Or, you can set gsh as your default shell. This is not recommended at the moment as gsh is still in early development. But if you know what you are doing, you can do so by:

# Get the absolute path to gsh by running `which gsh`
which gsh

# Add gsh to the list of approved shells
echo "/path/to/gsh" | sudo tee -a /etc/shells

# Change your default shell to gsh
chsh -s "/path/to/gsh"

gsh provides a set of default key bindings for navigating and editing text input. These key bindings are designed to be familiar to users of traditional shells and text editors. It's on the roadmap to allow users to customize these key bindings.

• Character Forward: Right Arrow, Ctrl+F
• Character Backward: Left Arrow, Ctrl+B
• Word Forward: Alt+Right Arrow, Ctrl+Right Arrow, Alt+F
• Word Backward: Alt+Left Arrow, Ctrl+Left Arrow, Alt+B
• Delete Word Backward: Alt+Backspace, Ctrl+W
• Delete Word Forward: Alt+Delete, Alt+D
• Delete After Cursor: Ctrl+K
• Delete Before Cursor: Ctrl+U
• Delete Character Backward: Backspace, Ctrl+H
• Delete Character Forward: Delete, Ctrl+D
• Line Start: Home, Ctrl+A
• Line End: End, Ctrl+E
• Paste: Ctrl+V

gsh provides a built-in command to use your recent command history to evaluate how well different LLM models work for predicting your commands. You can run the evaluation command with various options:

# Evaluate using the configured fast model
gsh> gsh_evaluate

# Evaluate using the configured fast model but change model id to mistral:7b
gsh> gsh_evaluate -m mistral:7b

# Control the number of recent commands to use for evaluation
gsh> gsh_evaluate -l 50  # evaluate with the most recent 50 commands you ran

# Run multiple iterations for more accurate results
gsh> gsh_evaluate -i 5  # run 5 iterations

Available options:

• -h, --help: Display help message
• -l, --limit <number>: Limit the number of entries to evaluate (default: 100)
• -m, --model <model-id>: Specify the model to use (default: use the default fast model)
• -i, --iterations <number>: Number of times to repeat the evaluation (default: 3)

You will get a report like below on how well the model performed in predicting the commands you recently ran.

┌────────────────────────┬──────────┬──────────┐
│Metric                  │Value     │Percentage│
├────────────────────────┼──────────┼──────────┤
│Model ID                │qwen2.5:3b│          │
│Current Iteration       │3/3       │          │
│Evaluated Entries       │300       │          │
│Prediction Errors       │0         │0.0%      │
│Perfect Predictions     │77        │25.7%     │
│Average Similarity      │0.38      │38.4%     │
│Average Latency         │0.9s      │          │
│Input Tokens Per Request│723.1     │          │
│Output Tokens Per Second│17.7      │          │
└────────────────────────┴──────────┴──────────┘

See ROADMAP.md for what's already planned. Feel free to suggest new features by opening an issue!

gsh is built on top of many great open source projects. Most notably:

• mvdan/sh - A shell parser, formatter, and interpreter
• bubbletea - A powerful little TUI framework
• zap - Blazing fast, structured, leveled logging in Go
• gorm - The fantastic ORM library for Golang
• go-openai - A Go client for the OpenAI API