Metadata-Version: 2.4
Name: runux
Version: 2.0.0
Summary: Plain English → Shell Commands. Free, local, oops-proof.
License: MIT License
        
        Copyright (c) 2025 Terminal Telepathy Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/aryankushwaha81780/runux
Project-URL: Repository, https://github.com/aryankushwaha81780/runux
Project-URL: Bug Tracker, https://github.com/aryankushwaha81780/runux/issues
Project-URL: Changelog, https://github.com/aryankushwaha81780/runux/blob/main/CHANGELOG.md
Keywords: cli,shell,llm,terminal,productivity,ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.28
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Dynamic: license-file

# ⚡ Runux `rx`

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

```bash
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)
```bash
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)
```bash
pip install --user runux
```

### From source (contributors only)
```bash
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
```bash
rx update
# or
pip install --upgrade runux
```

### Uninstall
```bash
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](https://console.groq.com/keys) | Cloud | 30 sec, no credit card |
| **Free local** | [Ollama](https://ollama.com) | 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:**
```bash
echo 'source /path/to/runux/shell/rx.zsh' >> ~/.zshrc
source ~/.zshrc
```

**Bash:**
```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.

```python
# ~/.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

```bash
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

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