Spren

Natural language to shell commands. Runs locally. No API keys needed.

spren> what is using my disk space

Suggested command: (5s)
du -h --max-depth=1 / 2>/dev/null | sort -hr

Execute? [y/N] y

Why Spren?

• 100% Local - Runs entirely on your CPU. No cloud, no API keys, no internet required
• Zero Config - Download, install, run. That's it
• Fast - ~5 second inference on modern CPUs
• Private - Your commands never leave your machine
• Smart - Context-aware: understands your current directory and git status
• Self-Healing - Auto-suggests fixes when commands fail
• Cross-Platform - Linux, macOS, Windows (Bash, Zsh, PowerShell, CMD)

Installation

Linux (Recommended)

# Download and install to PATH
curl -LO https://github.com/smadgulkar/spren-ai-terminal-assistant-rust/releases/latest/download/spren-linux-amd64.tar.gz
tar xzf spren-linux-amd64.tar.gz
sudo mv spren /usr/local/bin/
sudo mv models /usr/local/share/spren/

# Now use from anywhere
spren

Or install to user directory (no sudo):

mkdir -p ~/.local/bin ~/.local/share/spren
tar xzf spren-linux-amd64.tar.gz
mv spren ~/.local/bin/
mv models/* ~/.local/share/spren/

# Add to PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

macOS

curl -LO https://github.com/smadgulkar/spren-ai-terminal-assistant-rust/releases/latest/download/spren-macos-amd64.tar.gz
tar xzf spren-macos-amd64.tar.gz
sudo mv spren /usr/local/bin/
sudo mkdir -p /usr/local/share/spren
sudo mv models/* /usr/local/share/spren/

spren

Windows

1. Download spren-windows-amd64.zip from releases
2. Extract to a folder (e.g., C:\Program Files\Spren)
3. Add that folder to your PATH environment variable
4. Open a new terminal and run spren

Usage

Basic Mode (REPL)

spren

Interactive TUI Mode

spren --tui

Features: command editing, history navigation, visual interface

Single Query Mode

spren -q "list all large files"

Examples

spren> find all python files modified today
Suggested command: find . -name "*.py" -mtime 0

spren> show me running docker containers
Suggested command: docker ps

spren> compress this folder
Suggested command: tar -czvf folder.tar.gz folder/

spren> kill process on port 3000  
Suggested command: kill $(lsof -t -i:3000)

spren> what's my public IP
Suggested command: curl -s ifconfig.me

Features

Context-Aware Commands

Spren understands your environment:

~/my-project (git:main)$ spren
spren> show recent changes
Suggested command: git log --oneline -10

Auto-Fix Failed Commands

When a command fails, Spren automatically suggests a fix:

spren> list docker images

Suggested command: docker images
Execute? [y/N] y

Error: permission denied

Attempting to fix...
Fixed command: sudo docker images
Try fixed command? [y/N]

Interactive TUI

Run spren --tui for a full terminal interface:

• Edit commands before execution (Tab)
• Navigate history (Up/Down arrows)
• Visual feedback for dangerous commands

How It Works

Spren uses a fine-tuned Qwen2.5-0.5B model, quantized to 4-bit (Q4_K_M) for efficient CPU inference. The model was trained on 20,000+ shell command examples covering:

• File operations (ls, find, cp, mv, rm)
• Process management (ps, kill, top)
• Networking (curl, wget, ssh, ping)
• Package managers (apt, brew, pacman)
• Git, Docker, and more

The model runs via Candle, Hugging Face's Rust ML framework.

Requirements

• ~400MB disk space (model included)
• ~500MB RAM during inference
• Any modern CPU (no GPU required)

Cloud Mode (Optional)

If you prefer cloud APIs for faster/smarter responses, Spren also supports:

• Anthropic (Claude)
• OpenAI (GPT-4o)
• Google (Gemini)

Create a config file at ~/.config/spren/config.toml:

[ai]
provider = "openai"  # or "anthropic" or "gemini"
openai_api_key = "sk-..."

Building from Source

# Clone
git clone https://github.com/smadgulkar/spren-ai-terminal-assistant-rust.git
cd spren-ai-terminal-assistant-rust

# Download model files
mkdir -p models
curl -L -o models/spren-model.gguf "https://huggingface.co/smadgulkar/spren-shell-model/resolve/main/spren-model.gguf"
curl -L -o models/tokenizer.json "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/tokenizer.json"

# Build with all features
cargo build --release --features "local,tui"

# Run
./target/release/spren

Safety

Spren flags dangerous commands (like rm -rf) and always asks for confirmation before execution. You stay in control.

spren> delete everything in this folder

Suggested command: rm -rf ./* [DANGEROUS]

This command has been identified as potentially dangerous.
Execute? [y/N]

License

MIT

Links

• Model on Hugging Face
• Report Issues