OFFLINE • ON‑DEVICE • APPLE SILICON ONLY

SHELL SAGE

Describe what you want in plain English. Shell Sage runs a Gemma 4 model entirely on your Mac's Metal GPU and hands you the exact shell command — no cloud, no API keys, no data ever leaving your machine.

$ brew install mdev64/tap/shell-sage
View on GitHub Read the Docs
  • ⚡ 100% Offline
  • 🍎 Apple Silicon
  • 🔓 MIT Licensed
  • 🦀 Built in Rust

Why Shell Sage

A local-first companion for your terminal — no accounts, no telemetry, no internet required after setup.

⚡

100% Offline

Inference runs locally through llama-cpp-2 on the Metal GPU. No API keys, no cloud calls, no network required.

🧠

Generate Commands

sage "find all mp4 files" instantly produces a ready-to-run shell command tailored to your shell.

📖

Explain Commands

sage -e "tar -xzvf archive.tar.gz" breaks any command down flag by flag in plain language.

💬

Ask Questions

sage -a "why is the sky blue?" answers general-knowledge questions without leaving the terminal.

📋

Clipboard Ready

Optionally auto-copies the generated command — just ⌘ + V and press Enter.

⚙️

RAM-Aware Setup

The sage --config wizard detects your RAM and recommends the right Gemma 4 model size for your Mac.

See It In Action

Three modes, one assistant — all running on-device.

sage "…" — turn a plain-English request into a ready-to-run shell command.

sage -e "…" — get a plain-language, flag-by-flag breakdown of any command.

sage -a "…" — ask a general-knowledge question, right from the shell.

How It Works

Shell Sage suggests — it never executes anything on your behalf.

  1. 01

    Tokenize & Infer

    Your query is fed to a local Gemma 4 model via llama-cpp-2, running on the Metal GPU.

  2. 02

    Model Responds

    The model returns a raw shell command plus # -prefixed explanatory hints.

  3. 03

    Review Instantly

    Shell Sage prints the command and hints straight to your terminal for you to read.

  4. 04

    Paste & Run

    Optionally copied to your clipboard — press ⌘ + V, then Enter.

Installation

Pick Homebrew for the fastest setup, or build from source if you want full control.

brew install mdev64/tap/shell-sage
# 1. Install Xcode Command Line Tools (if not already installed)
xcode-select --install

# 2. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 3. Clone and build
git clone https://github.com/mdev64/shell-sage.git
cd shell-sage
cargo build --release

# 4. Put the binary on your PATH
cp target/release/sage /usr/local/bin/sage

Requirements

  • An Apple Silicon Mac (M1 / M2 / M3 / M4 or later). Intel Macs are not supported.
  • macOS with the Xcode Command Line Tools installed (needed for the Metal backend).
  • Rust (edition 2024, Rust 1.85+) — only required when building from source.

Quick Start

Run the setup wizard on first use — it detects your RAM, recommends a model, confirms your shell, and downloads model weights to ~/.cache/sage/.

sage --config

Then start generating commands:

sage "find all mp4 files"

Usage

Command What it does
sage "list files modified today" Generate a shell command
sage -e "ls -la" Explain a terminal command
sage -a "why is the sky blue?" Answer a general-knowledge question
sage --config Run the configuration wizard
sage --help Show help

Example

$ sage "compress all png files in this directory"

$ find . -name "*.png" -exec pngquant --ext .png {} \;
# find: searches the filesystem for files
# -name "*.png": matches files ending in .png
# -exec ...: runs pngquant on each match
✓ Command copied to clipboard. Press '⌘ + V', then press Enter to run.

Configuration

Settings persist in ~/.cache/sage/config.json and can be changed anytime with sage --config:

  • Model — Gemma 4 E2B (faster, lower RAM) or E4B (more capable, higher RAM).
  • Shell — the shell used in generated commands (e.g. /bin/zsh).
  • Code hints — toggle the # -prefixed explanations.
  • Clipboard — toggle auto-copying the command to the clipboard.

For Developers

Shell Sage is open source under the MIT License. Contributions are welcome.

Project Structure

src/
  main.rs       CLI parsing, mode dispatch, output rendering
  lib.rs        Crate root (public modules)
  config.rs     Model config, app settings, cache paths
  downloader.rs Model download, verification, cleanup
  engine.rs     Llama model loading and inference
  output.rs     Parse + sanitize the model's raw output
  prompt.rs     Prompt templates for each mode
  setup.rs      The `sage --config` interactive wizard
tests/
  *.rs          Integration tests (one per source module)

Development Workflow

  • Build: cargo build
  • Run: cargo run -- "your query"
  • Test: cargo test
  • Lint: cargo clippy --all-targets
  • Format: cargo fmt

Before submitting a pull request, make sure the following all pass:

cargo fmt --check
cargo clippy --all-targets
cargo test

Pull Request Process

  1. Open an issue describing the bug or feature first.
  2. Create a branch from main.
  3. Make focused, minimal changes.
  4. Add or update tests for any changed behavior.
  5. Run the checks above.
  6. Open a pull request describing what changed and why.

Reporting Bugs

When filing an issue, please include:

  • Your macOS version and Apple Silicon chip (e.g. macOS 15, M3)
  • The exact command you ran
  • The full terminal output
  • Your config (~/.cache/sage/config.json), with any personal info removed
Read CONTRIBUTING.md Open an Issue Fork the Repo