Smart-Shell

Smart-Shell turns plain English into Bash or Zsh commands, checks them for risk, and runs them after you confirm. It works with any OpenAI-compatible chat API: Gemini, OpenAI, DeepSeek, OpenRouter, Groq, or a local model through Ollama or LM Studio (fully offline).

Features

• Natural language to commands for Bash and Zsh, with the shell detected automatically.
• Any OpenAI-compatible provider. Built-in presets for gemini, openai, deepseek, openrouter, groq, ollama and lmstudio, plus custom for any base URL.
• Offline mode with Ollama or LM Studio: no API key, nothing leaves your machine.
• Safety checks on every command: blocked, high, medium, info_leak and safe. Blocked commands never run; high and medium need a y/n confirmation.
• Multi-step plans run in one shell, joined with &&, stopping at the first failure.
• Dry-run mode (--dry-run) to preview without executing.
• Interactive REPL with history and ! commands (!models, !model <name>, !redo, !errors, ...).
• No stored sudo password. sudo prompts in your terminal as usual.
• Self-update with !update, a desktop entry, and Bash/Zsh tab completion from the installer.

Install

curl -sSL https://raw.githubusercontent.com/Lusan-sapkota/smart-shell/main/install.sh | bash

The script installs Smart-Shell with uv (or pipx if you don't have uv), adds tab completion and a desktop entry, and runs the setup wizard.

Already use uv? Skip the script:

uv tool install git+https://github.com/Lusan-sapkota/smart-shell

Then:

smart-shell setup   # pick a provider, enter a key if needed, choose a default model
smart-shell         # start the interactive shell
smart-shell run "find files over 100MB in my home folder" --dry-run

To run fully offline with a local model, see Using local models (Ollama). For a manual or development install, see Development.

Uninstall

curl -sSL https://raw.githubusercontent.com/Lusan-sapkota/smart-shell/main/install.sh | bash -s -- --uninstall
rm -rf ~/.config/smart-shell ~/.local/share/smart-shell   # also delete config and history

Details in Uninstall.

Documentation

• Features
• Installation
• Usage
• Safety
• Uninstall
• Development
• API Reference
• FAQ
• Changelog
• Future Changes
• Contributing
• Author

Full documentation: smart-shell.lusansapkota.com.np.

License

Apache 2.0. See LICENSE.

Author

Created by Lusan Sapkota.

Disclaimer

Smart-Shell is an AI assistant and can generate wrong or unsafe commands. Always read a command before you confirm it, especially anything that modifies the system or touches sensitive data.