A security-first, offline, AI-assisted command-line helper for Linux
Command Butler is a local CLI agent that translates fuzzy human intent (e.g. "fix net", "list process") into safe, predefined Linux commands.
It is designed for control, safety, and transparency.
- 🧠 Local LLM (llama3.2:3b via Ollama) — no cloud, no API keys.
- 🔐 Strict Sandbox — AI only selects from
catalog/commands.json. - 🔁 Multi-step Agent Loop — Bounded for safety, fully inspectable.
- 🛡️ Sudo Escalation Loop — Intelligently handles "Permission denied" errors by prompting for sudo.
- 💬 Interactive Mode — Full REPL with command history (up-arrow support).
- 🔍 Command Discovery — Add new commands easily with
butler --cmd <name>. - ⚡ Fast & Lightweight — Built with Python, zero external dependencies besides Ollama.
- Ollama: Download and install
- Model:
ollama pull llama3.2:3b
git clone https://github.com/USER/BUTLER.git
cd BUTLER
./install.sh# Activate the environment
source .env/bin/activate
# Single command
butler "check network status"
# Interactive mode
butler --interactive
# Discovery mode (add new command to catalog)
butler --cmd htopbutler/
├── engine.py # Orchestrator
├── slm_decision.py # Intent → Command Selection
├── slm_analyzer.py # Output → Analysis
├── executor.py # Subprocess Runner (with sudo -S support)
├── logger.py # Audit logging
└── formatter.py # Box-style UI
catalog/
└── commands.json # The Allowlist
Key guarantees:
- AI NEVER generates raw shell strings.
- Only commands in the catalog can be executed.
- Human-in-the-loop for all critical actions.
Every action is recorded in history.jsonl (omitted from git). You can view what Butler did and why.
You can manually edit catalog/commands.json or use the built-in discovery tool:
butler --cmd "nmap"Butler will scan the manual pages and suggest a safe, descriptive entry for your catalog.
AI should assist, not take control.
Command Butler exists to keep humans in charge. Every action is a suggestion, every execution is verified.