runux 2.0.0

Plain English → Shell Commands. Free, local, oops-proof.

⚡ Runux rx

Plain English → Shell Commands · Free · Local · Oops-proof

rx kill whatever is using port 3000
rx find all jpg files bigger than 5mb and move them to ~/Pictures
rx explain "find . -name '*.log' -mtime +7 -exec rm {} ;"
rx plan set up a new Node project with ESLint and Prettier
rx oops          ← reverse the last command
rx recap         ← what you did this week
rx dash          ← full TUI dashboard

---

Install

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/aryankushwaha81780/runux/main/install.sh | bash

Source files are installed to ~/.local/lib/python3.x/site-packages/rx/ — completely hidden. The rx binary lands in ~/.local/bin/rx and is available from every terminal.

pip (if you already have Python)

pip install --user runux

From source (contributors only)

git clone https://github.com/aryankushwaha81780/runux
cd runux
pip install -e .

On first use, an interactive wizard walks you through choosing a backend. Run it manually any time with rx setup.

Keep up to date

rx update
# or
pip install --upgrade runux

Uninstall

pip uninstall runux
# optionally remove config + history:
rm -rf ~/.config/rx/

---

LLM Tiers — pick what works for you

Tier	Provider	Privacy	Setup
Free cloud	Groq	Cloud	30 sec, no credit card
Free local	Ollama	100% local	2 min + ~2 GB download
Paid	OpenAI / Anthropic	Cloud	Need API key
Offline	None	Local	Zero setup

note: `OpenAI / Anthropic' is a paid service and will be billed by them. you don't owe us nothing.

What's available in each tier

Feature	Offline	Non-Offline
Blast radius analyser	✓	✓
History & TUI dashboard	✓	✓
Streak tracking	✓	✓
Cheatsheet export	✓	✓
Share as GitHub Gist	✓	✓
Translate plain English	—	✓
Explain a command	—	✓
Undo generator (rx oops)	—	✓
Multi-step workflow planner	—	✓
Dry-run safety preview	—	✓
Weekly AI insight	—	✓
LLM-powered cheatsheet categories	—	✓

recommendation: llama-3.1-8b-instant on Groq's free tier gives you 500,000 tokens/day. A typical rx request uses ~300 tokens. You would need to run rx roughly 1,600 times a day to hit the limit. It will not happen.

---

Commands

Command	What it does
rx <intent>	Translate to shell and run
rx --sandbox <intent>	Preview inside Docker first
rx plan <intent>	Multi-step workflow with per-step confirm
rx explain <command>	Plain-English breakdown of any command
rx oops	Auto-generate and run the undo command
rx recap	Weekly stats + AI insight
rx history	Last 25 commands
rx dash	Full TUI dashboard with heatmap
rx export [--format md|html]	Personal cheatsheet
rx share	Share last command as a GitHub Gist
rx setup	Re-run the setup wizard
rx config	Show all settings
rx config set <key> <value>	Change a setting

---

Shell Integration (Ctrl+G keybind)

Type your intent on the command line, press Ctrl+G, and the generated command replaces your buffer — no need to type rx at all.

ZSH:

echo 'source /path/to/runux/shell/rx.zsh' >> ~/.zshrc
source ~/.zshrc

Bash:

echo 'source /path/to/runux/shell/rx.bash' >> ~/.bashrc
source ~/.bashrc

---

Safety System

Blast Radius Analyser

Every generated command is scanned for 18 danger patterns before you confirm: rm, kill, drop, --force, sudo, fork bombs, and more. If rm is detected, it automatically runs ls -lAh on the target so you see exactly what would vanish.

Dry-Run Preview

For rsync, find -exec, sed -i, and similar, rx automatically generates and runs the dry-run variant first, shows you the output, then asks "Run for real?"

Diff Preview

For sed -i and other in-place file editors, a colour diff is shown before execution.

Undo Generator

rx oops sends the last command to the LLM and asks for its exact inverse. Works for file moves, git operations, package installs, and more.

Docker Sandbox

rx --sandbox <intent> runs the generated command in a throwaway Alpine Linux container (read-only mount of your CWD) and shows you the output before running on your real machine.

---

Project Structure

runux/
├── rx/
│   ├── main.py                  ← orchestrator + first-run wizard trigger
│   ├── wizard.py                ← interactive setup menu
│   ├── features.py              ← tier detection + feature gate
│   ├── config.py                ← ~/.config/rx/config.json
│   ├── cli/
│   │   ├── parser.py            ← sys.argv → mode dict
│   │   ├── display.py           ← all rich output + feature-unavailable messages
│   │   ├── dashboard.py         ← TUI dashboard with heatmap
│   │   ├── export.py            ← Markdown / HTML cheatsheet generator
│   │   └── share.py             ← GitHub Gist sharing
│   ├── context/
│   │   ├── system_probe.py      ← OS / shell / cwd / SSH / Docker
│   │   ├── git_probe.py         ← branch, status, last commits
│   │   └── project_probe.py     ← Node / Python / Rust / Go detection
│   ├── ai/
│   │   ├── prompt_builder.py    ← all LLM prompt templates
│   │   └── client.py            ← Ollama · Groq · OpenAI · Anthropic
│   ├── execution/
│   │   ├── runner.py            ← subprocess with live streaming
│   │   ├── blast_radius.py      ← 18 danger patterns + ls preview
│   │   ├── dry_run.py           ← detects dry-run candidates
│   │   ├── diff_preview.py      ← colour diff for sed -i etc.
│   │   ├── sandbox.py           ← Docker throwaway container
│   │   ├── workflow.py          ← multi-step plan parser + runner
│   │   └── memory.py            ← SQLite: history, streak, stats
│   └── plugins/
│       └── loader.py            ← ~/.config/rx/plugins/*.py
├── shell/
│   ├── rx.zsh                   ← ZSH Ctrl+G keybind widget
│   └── rx.bash                  ← Bash Ctrl+G keybind widget
├── tests/
│   ├── conftest.py
│   ├── test_blast_radius.py
│   ├── test_features.py
│   ├── test_memory.py
│   ├── test_parser.py
│   ├── test_workflow.py
│   └── test_export.py
├── pyproject.toml
├── setup.sh
└── README.md

---

Plugin System

Drop a .py file into ~/.config/rx/plugins/ to extend rx without modifying it.

# ~/.config/rx/plugins/notify.py
# Send a macOS notification after every command.
import subprocess

def on_after_execute(command: str, output: str, returncode: int) -> None:
    title = "✓ Done" if returncode == 0 else "✗ Failed"
    subprocess.run(["osascript", "-e",
        f'display notification "{command[:60]}" with title "{title}"'])

Available hooks: on_before_translate(intent, ctx), on_command_generated(command, intent), on_after_execute(command, output, returncode).

---

Config Reference

rx config set provider        groq|ollama|openai|anthropic|none
rx config set model           llama-3.1-8b-instant   # or any model name
rx config set groq_api_key    gsk_...
rx config set openai_api_key  sk-...
rx config set alias_threshold 5       # suggest alias after N same intents
rx config set dry_run_first   true    # auto dry-run rsync/find/sed
rx config set sandbox_default false   # always use Docker sandbox
rx config set git_context     true    # include git info in prompts
rx config set streak_notify   true    # show streak after each run
rx config set github_token    ghp_... # for private Gists (optional)

---

Running Tests

pip install -e '.[dev]'
pytest -v