ShellSense Enhanced ✨

AI help in any terminal, on any machine — no setup required beyond Python itself.

ShellSense is a single-file, AI-powered command-line assistant that translates natural language into executable shell commands. Drop shell.py onto any machine, point it at an API key, and get instant AI assistance in your terminal — no package manager, no virtualenv, no installation ritual needed. If Python is present, ShellSense runs.

It connects to your preferred AI provider and generates platform-aware, ready-to-run commands by auto-detecting your OS, CPU architecture, and installed package managers — so the suggestions it gives you actually work on the system you're sitting at.

Zero hard dependencies beyond Python's standard library + requests. Every other library (rich, python-dotenv, readchar) is optional — ShellSense gracefully falls back to plain terminal output if they're absent.

---

Features

• Works Anywhere Python Runs — A single .py file is all you need. Copy it to any machine, server, container, or remote session and get AI assistance immediately — no pip install, no virtualenv, no build step required
• Broad OS Support — Runs natively on macOS, Windows, all major Linux distributions (Debian/Ubuntu, Fedora/RHEL/CentOS, Arch, SUSE, Alpine, Gentoo, and more), and BSD variants including FreeBSD and OpenBSD
• Multi-Provider AI Support — Works with OpenAI, Google Gemini, Groq, Anthropic Claude, OpenRouter, Azure OpenAI, GitHub Models, Ollama, and Pollinations
• OS-Aware Command Generation — Auto-detects your OS, architecture, and installed package managers to generate commands that actually work on your system
• Chat History — Persists conversation context across sessions for smarter suggestions
• Interactive Command Workflow — Execute, modify, revise, or quit suggested commands
• Auto-Fix on Failure — When a command fails, ShellSense captures the error and asks the AI for a fix
• .env File Support — Store API keys and preferences in a .env file alongside config.json
• Rich Terminal UI — Beautiful output with spinners, tables, and panels (gracefully falls back to plain text if Rich is unavailable)

---

Platform Support

ShellSense is tested and runs on:

Platform	Variants
Linux	Debian, Ubuntu, Fedora, RHEL, CentOS, Arch, Manjaro, SUSE, openSUSE, Alpine, Gentoo, and any distro with Python
macOS	Intel and Apple Silicon
Windows	Windows 10/11, PowerShell and CMD
BSD	FreeBSD, OpenBSD, NetBSD

Package manager detection covers apt, dnf, yum, pacman, zypper, apk, emerge, brew, snap, flatpak, nix-env, choco, winget, scoop, pkg, pip, npm, cargo, gem, go, and more — so AI suggestions are always tailored to what's actually available on your machine.

---

Supported AI Providers

Provider	Alias	Notes
OpenAI	openai	Requires OPENAI_API_KEY
Google Gemini	google_gemini, gemini	Requires GEMINI_API_KEY
Groq	groq	Requires GROQ_API_KEY
Anthropic Claude	anthropic, claude	Requires ANTHROPIC_API_KEY or CLAUDE_API_KEY
OpenRouter	openrouter	Requires OPENROUTER_API_KEY
Azure OpenAI	azure, azure_openai	Requires AZURE_API_KEY + AZURE_ENDPOINT
GitHub Models	gitazure, github	Requires GITHUB_API_KEY
Ollama	ollama	Local, no API key needed
Pollinations	pollinations	Free, no API key needed

---

Installation

Requirements

• Python 3.8+
• requests — the only true dependency (handles all API calls)
• rich — optional, for enhanced terminal UI
• python-dotenv — optional, for .env file support
• readchar — optional, for single-keypress confirmations

ShellSense will run with just Python and requests. All other libraries enhance the experience but are never required.

Install dependencies (optional but recommended)

pip install requests rich python-dotenv readchar

Install ShellSense system-wide

# Linux / macOS (installs to /usr/local/bin — may require sudo)
python shell.py --install

# Windows (installs to WindowsApps)
python shell.py --install

# Install to a custom directory
python shell.py --install . /your/custom/path

Create a configuration file only

python shell.py --install config

This creates config.json in the platform-appropriate config directory:

OS	Config Directory
Linux	~/.config/shellsense/
macOS	~/Library/Application Support/shellsense/
Windows	%APPDATA%\shellsense\

---

Configuration

Interactive API Setup

Run the interactive configurator to select a provider, enter your API key, and choose a model:

python shell.py --apiconfig

Manual config.json

The default configuration file looks like this:

{
    "api_key": "YOUR_API_KEY",
    "provider": "google_gemini",
    "model": "gemini-2.0-flash",
    "api_endpoint": "AZURE_API_ENDPOINT",
    "chat_history_enabled": true,
    "max_history_length": 10,
    "auto_env_vars": true,
    "use_dotenv": true,
    "create_env_file": true,
    "env_file_name": ".env"
}

.env File Support

ShellSense can read configuration from a .env file in the config directory. Create a template:

python shell.py --create-env

Example .env file:

GEMINI_API_KEY=AIzaSy...
MODEL=gemini-2.0-flash
PROVIDER=google_gemini

Supported environment variables:

Variable	Description
API_KEY	Generic API key (used as fallback)
OPENAI_API_KEY	OpenAI key
GEMINI_API_KEY	Google Gemini key
GROQ_API_KEY	Groq key
OPENROUTER_API_KEY	OpenRouter key
AZURE_API_KEY	Azure OpenAI key
GITHUB_API_KEY	GitHub Models key
ANTHROPIC_API_KEY / CLAUDE_API_KEY	Anthropic Claude key
MODEL	Model ID to use
PROVIDER	Provider name
API_ENDPOINT	Custom endpoint (Azure, Ollama, GitHub)

Environment variables and .env values take precedence over config.json.

---

Usage

Basic Usage

# Ask a natural language question
python shell.py "list all files modified in the last 7 days"

# Or after system-wide install
shellsense "find all jpg images larger than 5MB"

Interactive Workflow

After ShellSense suggests a command, you can:

• E — Execute the command directly
• M — Modify the command before running
• R — Revise and ask the AI for a different suggestion
• Q — Quit without executing

If a command fails, ShellSense captures the error output and offers to ask the AI for an automatic fix. You can also add your own feedback to guide the correction.

CLI Flags

Flag	Description
--config PATH	Path to a custom config.json
--apiconfig	Launch interactive API configuration wizard
--install [config|PATH]	Install system-wide or create config only
--create-env	Create a .env template file
--clear-history	Delete saved chat history
--no-history	Disable chat history for this session
--no-dotenv	Disable .env loading for this session
--debug	Enable verbose debug output

---

Chat History

ShellSense saves your previous interactions to chat_history.json in the config directory. Up to the last 3 interactions are included in each API request as context, improving the relevance of suggestions over time.

• Disable for a session: --no-history
• Clear all history: --clear-history or python shell.py --clear
• Configure retention: set max_history_length in config.json

---

How It Works

1. ShellSense detects your OS, CPU architecture, and all installed package managers (e.g., apt, brew, pip, cargo, npm, etc.)
2. It builds a system prompt with this information and sends your natural language query to the configured AI provider
3. The AI responds with one or more shell commands wrapped in backticks
4. ShellSense presents the command(s) and lets you execute, modify, or revise them
5. On execution, output is logged to a temporary file and the exit code is checked
6. If execution fails, the error is fed back to the AI for an automatic fix

---

Minimal / Zero-Dependency Mode

ShellSense is built to run on any machine with Python — even locked-down servers, fresh VMs, containers, or remote SSH sessions where you can't install packages freely.

The only true requirement beyond Python's standard library is requests, which handles all API communication. Everything else is optional:

• If rich is not installed, all output falls back to plain print() statements with no loss of functionality
• If python-dotenv is not installed, .env file loading is skipped and environment variables are still read from the shell environment
• If readchar is not installed, confirmations fall back to standard input()

This means you can drop shell.py onto virtually any machine, run pip install requests (or even use a system-installed requests), and have a fully functional AI terminal assistant immediately.

---

License

See the repository for license information.