ShellSage

A local shell agent powered by Ollama. Describe what you want in plain English and ShellSage proposes the exact shell command for your operating system, shows it before running, asks for confirmation on anything risky, runs it, and learns from what works.

Runs entirely on your machine. Tested on macOS and Linux; Windows support is implemented but experimental.

Why ShellSage

• Local-first. Your prompts and commands never leave your machine. The model runs through Ollama, not a cloud API.
• OS-aware. ShellSage detects your OS, shell, and package manager, so it suggests brew on a Mac, winget on Windows, and apt on Debian.
• It remembers. Commands that succeed are saved per-OS and reused instantly next time instead of being re-derived.
• It researches. When local knowledge falls short, ShellSage searches the web for the right command and caches the answer.
• It stays compliant. Task-specific skill files are injected into the prompt on the fly, keeping even small local models on the right track.
• Safe by default. Every command is shown before it runs. Destructive commands (like rm -rf /) are blocked outright, and risky ones (deletes, installs, permission changes) pause for your confirmation. Plain read-only commands run without a prompt.

Quick Start

ollama pull qwen2.5:3b          # 1. get the model
pip install -r requirements.txt # 2. install dependencies
python main.py                  # 3. run ShellSage

Or install it as a command so you can run shellsage from anywhere:

pip install -e .
shellsage                       # interactive
shellsage "list files here"     # one-shot

How It Works

   You: "list the largest files in this folder"
    │
    ▼
┌─────────────┐   known?    ┌──────────────┐
│   memory    │───────────► │    reuse     │
└─────────────┘   (yes)     └──────────────┘
    │ no
    ▼
┌──────────────┐
│     LLM      │  + OS context + matched skills
│   (Ollama)   │
└──────────────┘
    │
    ▼
┌──────────────┐
│    safety    │  block dangerous, confirm risky
└──────────────┘
    │
    ▼
┌──────────────┐   worked?   ┌──────────────┐
│     run      │───────────► │  remember    │
└──────────────┘   (yes)     └──────────────┘
    │ no
    ▼
┌──────────────┐   still no?  ┌──────────────┐
│   retry      │────────────► │   research   │  web + cache,
│ (variations) │              │  (fallback)  │  then run
└──────────────┘              └──────────────┘

Skills

Small local models drift without focused guidance. Instead of one bloated system prompt, ShellSage keeps short skill files in skills/ and injects only the ones relevant to your task. Each skill is a markdown file with trigger keywords and a few rules:

---
name: file-operations
description: Reading, listing, and inspecting files and folders
triggers: file, folder, read, show, cat, ls, size
---

- To show a file's contents, use `cat <file>`. Never use editors or pagers.
- For "this folder" or "current folder", use the current directory `.`.

When your task mentions a trigger word, that skill's rules are added to the prompt. Drop a new .md file in skills/ to teach ShellSage a new area — no code changes needed. Skills can be turned off with skills_enabled in the config.

Configuration

All settings live in config.py. Edit the CONFIG dictionary to change behavior — nothing is hardcoded elsewhere.

Setting	Default	Description
model	qwen2.5:3b	Ollama model to use
ollama_url	http://localhost:11434	Ollama server address
ollama_timeout	60	Request timeout in seconds
max_retries	3	Attempts before giving up on a task
max_research_results	3	Web snippets pulled per research query
command_idle_timeout	60	Seconds of no output before a command is stopped
command_max_timeout	3600	Absolute time ceiling in seconds (0 = no limit)
research_enabled	True	Allow web research
memory_enabled	True	Remember successful commands
safe_mode	True	Confirm risky commands before running
skills_enabled	True	Inject task-specific skill guidance
cache_expiry_days	7	How long research results stay cached
memory_match_threshold	0.5	Similarity needed to reuse a command
show_commands_before_run	True	Print each command before it runs
verbose	False	Extra output

Examples

A plain read-only command runs straight away:

shellsage> list the 10 largest files in this folder
⟳ Trying: du -ah . | sort -rh | head -n 10
...output...
✓ Here are the 10 largest files in this folder.

A risky command pauses for confirmation first:

shellsage> install ripgrep
Command: brew install ripgrep
Caution: Installs or upgrades software
Run this command? [y/N] y

A dangerous command is blocked outright, with a safer suggestion:

shellsage> wipe the root filesystem
✗ Blocked: Recursive force-delete of the root filesystem
Safer option: Target a specific folder instead, e.g. 'rm -rf ./build'

Limitations

ShellSage is honest about what it is — a local agent built on small models:

• Command quality tracks the model. The default qwen2.5:3b is fast and fully local, but small models can produce wrong or imperfect commands. Safety checks, confirmations, retries, and skills reduce the risk, but you should still read each command before approving it. For better accuracy, point model in config.py at a larger model.
• Success detection is best-effort. When a command's exit code is ambiguous, ShellSage asks the model whether the output indicates failure. This is usually right but can occasionally misjudge unusual output.
• Windows is experimental. The detection and safety logic cover Windows, but the end-to-end flow is primarily tested on macOS and Linux.
• Ollama must be running locally. ShellSage talks to Ollama over HTTP; it does not fall back to any cloud API.

Contributing

Contributions are welcome. The codebase follows a few simple rules:

• Every function does one thing and has a docstring.
• Every file has one responsibility.
• No hardcoded values — put them in config.py.
• No dead code or commented-out blocks.

The test suite runs offline (Ollama is stubbed), so no model is required:

pip install -e ".[dev]"
pytest

Open an issue to discuss larger changes, then send a pull request.

License

Released under the MIT License.