shix 0.1.0__tar.gz

shix-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip3 install:*)",
+      "Bash(python3 -m pip show textual)"
+    ]
+  }
+}

shix-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+.DS_Store

shix-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: shix
+Version: 0.1.0
+Summary: Find and run shell commands using natural language, powered by your shell history and local AI
+Project-URL: Homepage, https://github.com/nicla97/shix
+Project-URL: Repository, https://github.com/nicla97/shix
+Project-URL: Issues, https://github.com/nicla97/shix/issues
+Author-email: Nicolaj Larsen <nicla97@github.com>
+License-Expression: MIT
+Keywords: cli,command,history,search,shell,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.50.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: local
+Requires-Dist: httpx>=0.25.0; extra == 'local'
+Description-Content-Type: text/markdown
+
+# shix
+
+Find and run shell commands using natural language — powered by your own shell history.
+
+shix searches your shell history to suggest relevant commands based on what you describe. No cloud, no API keys, just your local history.
+
+## Install
+
+```bash
+pip install git+https://github.com/nicla97/shix.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/nicla97/shix.git
+cd shix
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Describe what you want to do
+shix ask "docker compose restart"
+shix ask "git push"
+shix ask "activate virtual environment"
+
+# Show more results
+shix ask "git" --top 15
+
+# Use a local AI model via Ollama (optional)
+shix ask "find all large files" --local
+```
+
+An interactive TUI opens where you can:
+
+- **Arrow keys** to navigate between suggestions
+- **Enter** or **click** to copy a command to clipboard
+- **Mouse hover** to highlight a suggestion
+- **Scroll** through many results
+- **Esc** or **q** to quit
+
+## Modes
+
+### Offline (default)
+
+Fuzzy keyword search on your shell history. Instant results, no dependencies beyond Python.
+
+```bash
+shix ask "docker compose"
+```
+
+### Local AI (`--local`)
+
+Sends your sanitized history to a local [Ollama](https://ollama.com) model for smarter, context-aware suggestions.
+
+```bash
+# First time setup
+ollama pull qwen2.5:7b
+ollama serve  # keep running in another terminal
+
+# OR RUN THE OLLAMA APP
+
+# Then use --local
+shix ask "find files older than 7 days" --local
+```
+
+Requires the optional `httpx` dependency:
+
+```bash
+pip install shix[local]
+# or just: pip install httpx
+```
+
+## Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--top N` | `-t` | Number of suggestions (default: 5) |
+| `--local` | `-l` | Use local Ollama model |
+| `--model NAME` | `-m` | Ollama model to use (default: qwen2.5:7b) |
+| `--history N` | `-n` | Limit history lines (0 = all, default: 0) |
+| `--version` | `-v` | Show version |
+
+## How it works
+
+1. Reads your shell history (`~/.zsh_history`, `~/.bash_history`, or PowerShell history on Windows)
+2. Sanitizes secrets (API keys, passwords, tokens) before processing
+3. Matches your query against history using fuzzy search (or sends to Ollama with `--local`)
+4. Displays results in an interactive TUI for quick selection
+
+## Supported shells
+
+- **zsh** (macOS/Linux)
+- **bash** (macOS/Linux)
+- **PowerShell** (Windows)
+
+## License
+
+MIT

shix-0.1.0/README.md

@@ -0,0 +1,101 @@
+# shix
+
+Find and run shell commands using natural language — powered by your own shell history.
+
+shix searches your shell history to suggest relevant commands based on what you describe. No cloud, no API keys, just your local history.
+
+## Install
+
+```bash
+pip install git+https://github.com/nicla97/shix.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/nicla97/shix.git
+cd shix
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Describe what you want to do
+shix ask "docker compose restart"
+shix ask "git push"
+shix ask "activate virtual environment"
+
+# Show more results
+shix ask "git" --top 15
+
+# Use a local AI model via Ollama (optional)
+shix ask "find all large files" --local
+```
+
+An interactive TUI opens where you can:
+
+- **Arrow keys** to navigate between suggestions
+- **Enter** or **click** to copy a command to clipboard
+- **Mouse hover** to highlight a suggestion
+- **Scroll** through many results
+- **Esc** or **q** to quit
+
+## Modes
+
+### Offline (default)
+
+Fuzzy keyword search on your shell history. Instant results, no dependencies beyond Python.
+
+```bash
+shix ask "docker compose"
+```
+
+### Local AI (`--local`)
+
+Sends your sanitized history to a local [Ollama](https://ollama.com) model for smarter, context-aware suggestions.
+
+```bash
+# First time setup
+ollama pull qwen2.5:7b
+ollama serve  # keep running in another terminal
+
+# OR RUN THE OLLAMA APP
+
+# Then use --local
+shix ask "find files older than 7 days" --local
+```
+
+Requires the optional `httpx` dependency:
+
+```bash
+pip install shix[local]
+# or just: pip install httpx
+```
+
+## Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--top N` | `-t` | Number of suggestions (default: 5) |
+| `--local` | `-l` | Use local Ollama model |
+| `--model NAME` | `-m` | Ollama model to use (default: qwen2.5:7b) |
+| `--history N` | `-n` | Limit history lines (0 = all, default: 0) |
+| `--version` | `-v` | Show version |
+
+## How it works
+
+1. Reads your shell history (`~/.zsh_history`, `~/.bash_history`, or PowerShell history on Windows)
+2. Sanitizes secrets (API keys, passwords, tokens) before processing
+3. Matches your query against history using fuzzy search (or sends to Ollama with `--local`)
+4. Displays results in an interactive TUI for quick selection
+
+## Supported shells
+
+- **zsh** (macOS/Linux)
+- **bash** (macOS/Linux)
+- **PowerShell** (Windows)
+
+## License
+
+MIT

shix-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shix"
+version = "0.1.0"
+description = "Find and run shell commands using natural language, powered by your shell history and local AI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Nicolaj Larsen", email = "nicla97@github.com" },
+]
+keywords = ["cli", "shell", "history", "command", "search", "terminal", "tui"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Shells",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "textual>=0.50.0",
+    "pyperclip>=1.8.0",
+]
+
+[project.optional-dependencies]
+local = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://github.com/nicla97/shix"
+Repository = "https://github.com/nicla97/shix"
+Issues = "https://github.com/nicla97/shix/issues"
+
+[project.scripts]
+shix = "shix.cli:app"

shix-0.1.0/shix/__init__.py

@@ -0,0 +1,3 @@
+"""shix — find and run shell commands using natural language."""
+
+__version__ = "0.1.0"

shix-0.1.0/shix/cli.py

@@ -0,0 +1,126 @@
+"""shix CLI — find shell commands using natural language."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from shix import __version__
+from shix.history import read_history
+from shix.sanitize import sanitize
+from shix.tui import SuggestionItem, run_tui
+
+app = typer.Typer(
+    name="shix",
+    help="Find and run shell commands using natural language.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def ask(
+    query: str = typer.Argument(..., help="Describe what you want to do"),
+    top: int = typer.Option(5, "--top", "-t", help="Number of suggestions to show"),
+    local: bool = typer.Option(False, "--local", "-l", help="Use local Ollama model instead of offline search"),
+    model: str = typer.Option("qwen2.5:7b", "--model", "-m", help="Ollama model (only with --local)"),
+    base_url: str = typer.Option("http://localhost:11434", "--url", "-u", help="Ollama server URL (only with --local)"),
+    history_lines: int = typer.Option(0, "--history", "-n", help="Number of history lines to read (0 = all)"),
+) -> None:
+    """Describe what you want to do and get command suggestions."""
+    with console.status("[bold cyan]  Reading shell history..."):
+        history = read_history(max_lines=history_lines)
+
+    if not history:
+        console.print("[yellow]  No shell history found.[/yellow]")
+        if local:
+            history = []
+        else:
+            console.print("[yellow]  Offline mode needs history. Try --local for AI suggestions.[/yellow]")
+            raise typer.Exit(1)
+
+    clean_history = sanitize(history)
+
+    if local:
+        _run_local(clean_history, query, model, base_url, top)
+    else:
+        _run_offline(history, query, top)
+
+
+def _run_offline(history: list[str], query: str, top: int = 5) -> None:
+    """Fuzzy search through history — no model, instant results."""
+    from shix.fuzzy import fuzzy_search, _tokenize
+
+    results = fuzzy_search(history, query, max_results=top)
+
+    query_tokens = _tokenize(query)
+    history_blob = " ".join(history).lower()
+    missing = [t for t in query_tokens if t not in history_blob]
+
+    items = [
+        SuggestionItem(command=r.command, explanation=r.reason)
+        for r in results
+    ]
+
+    result = run_tui(items, query, "offline", missing if missing else None)
+    if result:
+        console.print(f"[green]Copied:[/green] {result}")
+
+
+def _run_local(history: list[str], query: str, model: str, base_url: str, top: int = 5) -> None:
+    """Query local Ollama model for suggestions."""
+    try:
+        from shix.ollama import get_suggestions
+    except ImportError:
+        console.print(
+            "[red]  Missing dependency for --local mode.[/red]\n"
+            "  Install with: [bold]pip install shix\\[local][/bold]  (or: pip install httpx)"
+        )
+        raise typer.Exit(1)
+
+    with console.status("[bold cyan]  Thinking..."):
+        try:
+            suggestions = get_suggestions(
+                history=history,
+                query=query,
+                model=model,
+                base_url=base_url,
+                count=top,
+            )
+        except Exception as e:
+            error_msg = str(e)
+            if "ConnectError" in type(e).__name__ or "Connection" in error_msg:
+                console.print(
+                    "[red]  Could not connect to Ollama.[/red]\n"
+                    "  Make sure Ollama is running: [bold]ollama serve[/bold]\n"
+                    f"  And that the model is pulled: [bold]ollama pull {model}[/bold]"
+                )
+            else:
+                console.print(f"[red]  Error: {error_msg}[/red]")
+            raise typer.Exit(1)
+
+    items = [
+        SuggestionItem(command=s.command, explanation=s.explanation)
+        for s in suggestions
+    ]
+
+    result = run_tui(items, query, f"local ({model})")
+    if result:
+        console.print(f"[green]Copied:[/green] {result}")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: Optional[bool] = typer.Option(None, "--version", "-v", help="Show version", is_eager=True),
+) -> None:
+    """shix — find shell commands using natural language."""
+    if version:
+        console.print(f"shix {__version__}")
+        raise typer.Exit()
+
+
+if __name__ == "__main__":
+    app()

shix-0.1.0/shix/fuzzy.py

@@ -0,0 +1,138 @@
+"""Offline fuzzy search engine for shell history."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Map natural language terms to common command patterns
+COMMAND_ALIASES: dict[str, list[str]] = {
+    "find": ["find", "locate", "fd", "ls", "grep", "rg"],
+    "delete": ["rm", "rmdir", "trash", "del"],
+    "copy": ["cp", "rsync", "scp"],
+    "move": ["mv"],
+    "search": ["grep", "rg", "ag", "ack", "find"],
+    "install": ["brew install", "apt install", "pip install", "npm install", "cargo install"],
+    "process": ["ps", "top", "htop", "kill", "pkill"],
+    "network": ["curl", "wget", "ping", "netstat", "ss", "nmap", "dig", "nslookup"],
+    "disk": ["df", "du", "ncdu"],
+    "docker": ["docker", "docker-compose", "podman"],
+    "git": ["git"],
+    "size": ["du", "ls -l", "wc", "stat"],
+    "permission": ["chmod", "chown", "chgrp"],
+    "compress": ["tar", "zip", "gzip", "bzip2", "xz", "7z"],
+    "extract": ["tar", "unzip", "gunzip"],
+    "edit": ["vim", "nvim", "nano", "code", "emacs"],
+    "serve": ["python -m http.server", "npx serve", "nginx"],
+    "port": ["lsof -i", "netstat", "ss"],
+    "log": ["tail", "less", "journalctl", "cat"],
+    "ssh": ["ssh", "scp", "sftp"],
+    "env": ["env", "printenv", "export", "set"],
+    "start": ["systemctl start", "docker start", "npm start", "brew services start"],
+    "stop": ["systemctl stop", "docker stop", "kill", "pkill", "brew services stop"],
+    "restart": ["systemctl restart", "docker restart", "brew services restart"],
+    "list": ["ls", "ll", "exa", "tree"],
+    "download": ["curl", "wget", "aria2c"],
+    "upload": ["scp", "rsync", "curl -X POST"],
+}
+
+
+@dataclass
+class FuzzyResult:
+    command: str
+    score: float
+    reason: str
+
+
+def _tokenize(text: str) -> list[str]:
+    """Split text into lowercase tokens."""
+    return re.findall(r"[a-zA-Z0-9_./-]+", text.lower())
+
+
+def _score_command(command: str, query_tokens: list[str], alias_commands: set[str]) -> tuple[float, str]:
+    """Score a command against the query. Returns (score, reason)."""
+    cmd_lower = command.lower()
+    cmd_tokens = _tokenize(command)
+    score = 0.0
+    reasons: list[str] = []
+
+    # Direct token matches — substring in the full command text
+    matched_tokens = [t for t in query_tokens if t in cmd_lower]
+    unmatched_tokens = [t for t in query_tokens if t not in cmd_lower]
+
+    if matched_tokens:
+        score += len(matched_tokens) * 3.0
+        reasons.append(f"matches: {', '.join(matched_tokens)}")
+
+    # Bonus: reward commands that match ALL query tokens (multi-term relevance)
+    if len(query_tokens) > 1 and matched_tokens:
+        coverage = len(matched_tokens) / len(query_tokens)
+        score += coverage * 5.0  # full match = +5, half match = +2.5
+
+    # Alias matches — only match against the first token (the actual command)
+    cmd_base = cmd_tokens[0] if cmd_tokens else ""
+    for alias_cmd in alias_commands:
+        alias_parts = alias_cmd.lower().split()
+        if len(alias_parts) == 1 and cmd_base == alias_parts[0]:
+            score += 2.0
+            reasons.append(f"relates to: {alias_cmd}")
+            break
+        elif len(alias_parts) > 1 and cmd_lower.startswith(alias_cmd.lower()):
+            score += 2.5
+            reasons.append(f"relates to: {alias_cmd}")
+            break
+
+    # Partial/substring matches on unmatched tokens — check against first few command tokens
+    cmd_head_tokens = cmd_tokens[:3]
+    for token in unmatched_tokens:
+        if len(token) >= 4:
+            for cmd_token in cmd_head_tokens:
+                if token in cmd_token or cmd_token in token:
+                    score += 1.0
+                    reasons.append(f"~{token}")
+                    break
+
+    if score == 0:
+        return 0.0, ""
+
+    reason = "; ".join(reasons) if reasons else "partial match"
+    return score, reason
+
+
+def fuzzy_search(history: list[str], query: str, max_results: int = 3) -> list[FuzzyResult]:
+    """Search shell history using fuzzy keyword matching.
+
+    Matches query tokens against commands and uses alias mappings
+    to connect natural language terms to shell commands.
+    """
+    query_tokens = _tokenize(query)
+    if not query_tokens:
+        return []
+
+    # Build set of relevant command patterns from aliases
+    alias_commands: set[str] = set()
+    for token in query_tokens:
+        for alias_key, commands in COMMAND_ALIASES.items():
+            if token in alias_key or alias_key in token:
+                alias_commands.update(commands)
+
+    # Score all history commands
+    scored: list[FuzzyResult] = []
+    for cmd in history:
+        score, reason = _score_command(cmd, query_tokens, alias_commands)
+        if score > 0:
+            scored.append(FuzzyResult(command=cmd, score=score, reason=reason))
+
+    # Sort by score descending, deduplicate
+    scored.sort(key=lambda r: r.score, reverse=True)
+
+    seen: set[str] = set()
+    results: list[FuzzyResult] = []
+    for r in scored:
+        if r.command not in seen:
+            seen.add(r.command)
+            results.append(r)
+            if len(results) >= max_results:
+                break
+
+    return results

shix-0.1.0/shix/history.py

@@ -0,0 +1,125 @@
+"""Cross-platform shell history reader."""
+
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+
+
+def _get_history_paths() -> list[Path]:
+    """Return candidate history file paths for the current platform."""
+    home = Path.home()
+    system = platform.system()
+
+    if system == "Windows":
+        # PowerShell PSReadLine history
+        appdata = os.environ.get("APPDATA", "")
+        if appdata:
+            ps_history = Path(appdata) / "Microsoft" / "Windows" / "PowerShell" / "PSReadLine" / "ConsoleHost_history.txt"
+            return [ps_history]
+        return []
+
+    # macOS / Linux — prefer zsh, fall back to bash
+    return [
+        home / ".zsh_history",
+        home / ".bash_history",
+    ]
+
+
+def _parse_zsh_history_line(raw: str) -> str | None:
+    """Parse a single zsh history line, handling the extended format.
+
+    Zsh extended history format: `: <timestamp>:<duration>;<command>`
+    Regular format: just the command.
+    Multi-line commands use trailing backslash continuation.
+    """
+    line = raw.strip()
+    if not line:
+        return None
+
+    # Extended history format
+    if line.startswith(": ") and ";" in line:
+        _, _, rest = line.partition(";")
+        return rest.strip() or None
+
+    return line
+
+
+def _read_file_tail(path: Path, max_lines: int = 0) -> list[str]:
+    """Read lines from a file. If max_lines > 0, return only the last N lines."""
+    try:
+        raw = path.read_bytes()
+    except (OSError, PermissionError):
+        return []
+
+    # Try utf-8 first, fall back to latin-1 (never fails)
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("latin-1")
+
+    lines = text.splitlines()
+    return lines[-max_lines:] if max_lines > 0 else lines
+
+
+def read_history(max_lines: int = 0) -> list[str]:
+    """Read the most recent shell commands from history.
+
+    Tries platform-appropriate history files in priority order.
+    Returns deduplicated commands preserving most-recent order.
+    """
+    paths = _get_history_paths()
+
+    for path in paths:
+        if not path.exists():
+            continue
+
+        raw_lines = _read_file_tail(path, max_lines * 2 if max_lines > 0 else 0)
+
+        # Determine if this is a zsh history file
+        is_zsh = "zsh" in path.name.lower()
+
+        commands: list[str] = []
+        if is_zsh:
+            # Handle multi-line commands (backslash continuation)
+            buffer = ""
+            for raw in raw_lines:
+                if buffer:
+                    buffer += "\n" + raw.rstrip("\\").strip()
+                    if not raw.endswith("\\"):
+                        commands.append(buffer)
+                        buffer = ""
+                    continue
+
+                if raw.rstrip().endswith("\\"):
+                    parsed = _parse_zsh_history_line(raw.rstrip("\\"))
+                    if parsed:
+                        buffer = parsed
+                    continue
+
+                parsed = _parse_zsh_history_line(raw)
+                if parsed:
+                    commands.append(parsed)
+
+            if buffer:
+                commands.append(buffer)
+        else:
+            # bash / PowerShell — plain line-per-command
+            for raw in raw_lines:
+                line = raw.strip()
+                if line:
+                    commands.append(line)
+
+        # Deduplicate keeping last occurrence (most recent)
+        seen: set[str] = set()
+        unique: list[str] = []
+        for cmd in reversed(commands):
+            if cmd not in seen:
+                seen.add(cmd)
+                unique.append(cmd)
+        unique.reverse()
+
+        return unique[-max_lines:] if max_lines > 0 else unique
+
+    return []

shix-0.1.0/shix/ollama.py

@@ -0,0 +1,111 @@
+"""Ollama integration for generating command suggestions."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+import httpx
+
+DEFAULT_MODEL = "qwen2.5:7b"
+DEFAULT_BASE_URL = "http://localhost:11434"
+
+SYSTEM_PROMPT = """\
+You are shix, a shell command assistant. The user will describe what they want to do, \
+and you will suggest shell commands based on their shell history and request.
+
+Rules:
+- Return the number of suggestions the user asks for, ranked by relevance
+- Each suggestion has a "command" and a short "explanation" (one sentence)
+- Only suggest commands that are likely to work on the user's system based on their history
+- If the history shows usage of specific tools (e.g. docker, kubectl, git), prefer those
+- Output valid JSON only, no markdown fences, no extra text
+
+Output format (JSON array):
+[
+  {"command": "...", "explanation": "..."},
+  ...
+]
+"""
+
+
+@dataclass
+class Suggestion:
+    command: str
+    explanation: str
+
+
+def _build_prompt(history: list[str], query: str, count: int = 5) -> str:
+    """Build the user prompt with history context and query."""
+    history_block = "\n".join(history[-200:])  # trim to fit context
+    return (
+        f"Here are my recent shell commands for context:\n"
+        f"```\n{history_block}\n```\n\n"
+        f"I want to: {query}\n\n"
+        f"Suggest {count} commands as a JSON array."
+    )
+
+
+def _parse_suggestions(text: str) -> list[Suggestion]:
+    """Parse the model response into Suggestion objects."""
+    # Try to find JSON array in the response
+    # Strip markdown code fences if present
+    cleaned = re.sub(r"```(?:json)?\s*", "", text)
+    cleaned = cleaned.strip().rstrip("`")
+
+    # Find the JSON array
+    match = re.search(r"\[.*\]", cleaned, re.DOTALL)
+    if not match:
+        return []
+
+    try:
+        data = json.loads(match.group())
+    except json.JSONDecodeError:
+        return []
+
+    suggestions = []
+    for item in data:
+        if isinstance(item, dict) and "command" in item:
+            suggestions.append(
+                Suggestion(
+                    command=str(item["command"]),
+                    explanation=str(item.get("explanation", "")),
+                )
+            )
+    return suggestions
+
+
+def get_suggestions(
+    history: list[str],
+    query: str,
+    model: str = DEFAULT_MODEL,
+    base_url: str = DEFAULT_BASE_URL,
+    count: int = 5,
+) -> list[Suggestion]:
+    """Query Ollama for command suggestions.
+
+    Raises httpx.ConnectError if Ollama is not running.
+    """
+    prompt = _build_prompt(history, query, count)
+
+    response = httpx.post(
+        f"{base_url}/api/chat",
+        json={
+            "model": model,
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt},
+            ],
+            "stream": False,
+            "options": {
+                "temperature": 0.3,
+            },
+        },
+        timeout=120.0,
+    )
+    response.raise_for_status()
+
+    body = response.json()
+    content = body.get("message", {}).get("content", "")
+    return _parse_suggestions(content)

shix-0.1.0/shix/sanitize.py

@@ -0,0 +1,89 @@
+"""Sanitize shell history by redacting secrets, tokens, and passwords."""
+
+from __future__ import annotations
+
+import re
+
+REDACTED = "<REDACTED>"
+
+# Patterns that match common secret formats in shell commands
+_PATTERNS: list[re.Pattern[str]] = [
+    # API keys / tokens passed as env vars or flags (KEY=value, --token=value, --token value)
+    re.compile(
+        r"(?i)(api[_-]?key|api[_-]?secret|token|secret|password|passwd|pwd|auth)"
+        r"[\s=:]+['\"]?([A-Za-z0-9_\-./+]{8,})['\"]?"
+    ),
+    # Bearer tokens
+    re.compile(r"(?i)(bearer\s+)([A-Za-z0-9_\-./+]{8,})"),
+    # AWS-style keys (AKIA...)
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    # Generic long hex/base64 strings that look like secrets (32+ chars)
+    re.compile(r"(?i)(?:key|token|secret|password|credential)s?\s*[=:]\s*['\"]?([A-Za-z0-9_\-./+]{32,})['\"]?"),
+    # URLs with embedded credentials (https://user:pass@host)
+    re.compile(r"(https?://)([^:]+):([^@]+)@"),
+    # export VAR=secret patterns
+    re.compile(r"(?i)export\s+\w*(secret|token|key|password|passwd|api|auth)\w*\s*=\s*['\"]?(.+?)['\"]?\s*$"),
+    # -p password or --password=xxx
+    re.compile(r"(?i)(-p\s+|--password[=\s]+)['\"]?(\S+)['\"]?"),
+    # SSH private key paths are fine, but inline keys are not
+    re.compile(r"-----BEGIN[A-Z ]+PRIVATE KEY-----"),
+    # GitHub/GitLab personal access tokens (ghp_, glpat-, etc.)
+    re.compile(r"(ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-]{20,})"),
+    # npm tokens
+    re.compile(r"npm_[A-Za-z0-9]{36}"),
+]
+
+
+def _redact_line(line: str) -> str:
+    """Redact secrets from a single history line."""
+    result = line
+
+    # URL credentials: https://user:pass@host -> https://***:***@host
+    result = re.sub(
+        r"(https?://)([^:]+):([^@]+)@",
+        rf"\1{REDACTED}:{REDACTED}@",
+        result,
+    )
+
+    # -p password flag
+    result = re.sub(
+        r"(?i)(-p\s+|--password[=\s]+)['\"]?\S+['\"]?",
+        rf"\1{REDACTED}",
+        result,
+    )
+
+    # export SECRET_VAR=value
+    result = re.sub(
+        r"(?i)(export\s+\w*(?:secret|token|key|password|passwd|api|auth)\w*\s*=\s*)['\"]?.+?['\"]?\s*$",
+        rf"\1{REDACTED}",
+        result,
+    )
+
+    # KEY=value, --token=value, --token value
+    result = re.sub(
+        r"(?i)((?:api[_-]?key|api[_-]?secret|token|secret|password|passwd|pwd|auth)[\s=:]+)['\"]?[A-Za-z0-9_\-./+]{8,}['\"]?",
+        rf"\1{REDACTED}",
+        result,
+    )
+
+    # Bearer tokens
+    result = re.sub(
+        r"(?i)(bearer\s+)[A-Za-z0-9_\-./+]{8,}",
+        rf"\1{REDACTED}",
+        result,
+    )
+
+    # AWS keys
+    result = re.sub(r"AKIA[0-9A-Z]{16}", REDACTED, result)
+
+    # GitHub/GitLab tokens
+    result = re.sub(r"ghp_[A-Za-z0-9]{36}", REDACTED, result)
+    result = re.sub(r"glpat-[A-Za-z0-9\-]{20,}", REDACTED, result)
+    result = re.sub(r"npm_[A-Za-z0-9]{36}", REDACTED, result)
+
+    return result
+
+
+def sanitize(commands: list[str]) -> list[str]:
+    """Sanitize a list of shell commands by redacting secrets."""
+    return [_redact_line(cmd) for cmd in commands]

shix-0.1.0/shix/tui.py

@@ -0,0 +1,273 @@
+"""Textual TUI app for shix — interactive command suggestion browser."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.message import Message
+from textual.widgets import Static, Label
+
+
+@dataclass
+class SuggestionItem:
+    command: str
+    explanation: str
+
+
+class CommandPill(Static, can_focus=True):
+    """A focusable pill-shaped command suggestion."""
+
+    BINDINGS = [
+        Binding("up,left,k", "app.focus_prev", show=False),
+        Binding("down,right,j", "app.focus_next", show=False),
+        Binding("enter", "app.select", show=False),
+    ]
+
+    class Selected(Message):
+        def __init__(self, command: str) -> None:
+            self.command = command
+            super().__init__()
+
+    def __init__(self, command: str, **kwargs) -> None:
+        display = command.split("\n")[0]
+        super().__init__(display, **kwargs)
+        self.command = command
+
+    def on_enter(self, event) -> None:
+        self.focus(scroll_visible=False)
+
+    def on_click(self) -> None:
+        self.post_message(self.Selected(self.command))
+
+
+class ResultRow(Horizontal):
+    """A row containing an index label and a command pill."""
+
+    DEFAULT_CSS = """
+    ResultRow {
+        height: 1;
+        width: 100%;
+        margin-bottom: 1;
+    }
+    """
+
+    def on_enter(self, event) -> None:
+        pill = self.query_one(CommandPill)
+        pill.focus(scroll_visible=False)
+
+    def on_click(self) -> None:
+        pill = self.query_one(CommandPill)
+        pill.post_message(CommandPill.Selected(pill.command))
+
+
+class PillsContainer(Container, can_focus=False):
+    """A container that does not capture key events."""
+
+    DEFAULT_CSS = """
+    PillsContainer {
+        height: 1fr;
+        overflow-y: auto;
+    }
+    """
+
+
+class ShixApp(App):
+    """Interactive command suggestion browser."""
+
+    TITLE = "shix"
+    COMMAND_PALETTE_BINDING = "ctrl+p"
+
+    CSS = """
+    Screen {
+        background: #0d1117;
+        padding: 1 2;
+    }
+
+    #title-text {
+        color: #58a6ff;
+        height: 1;
+    }
+
+    #query-text {
+        color: #e6edf3;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    #warning {
+        color: #d29922;
+        height: 1;
+        margin-top: 1;
+        display: none;
+    }
+
+    #warning.visible {
+        display: block;
+    }
+
+    #pills-label {
+        color: #484f58;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    .pill-index {
+        width: 4;
+        height: 1;
+        color: #484f58;
+        padding: 0 1 0 0;
+        content-align: right middle;
+    }
+
+    CommandPill {
+        width: auto;
+        height: 1;
+        max-width: 1fr;
+        padding: 0 2;
+        color: #8b949e;
+        background: #21262d;
+    }
+
+    CommandPill:hover {
+        background: #30363d;
+        color: #c9d1d9;
+    }
+
+    CommandPill:focus {
+        background: #1f6feb;
+        color: #ffffff;
+        text-style: bold;
+    }
+
+    #status-bar {
+        dock: bottom;
+        height: 1;
+        background: #010409;
+        color: #484f58;
+        padding: 0 2;
+    }
+
+    #status-bar.copied {
+        background: #238636;
+        color: #ffffff;
+        text-style: bold;
+    }
+
+    Footer {
+        display: none;
+    }
+    """
+
+    BINDINGS = [
+        Binding("up,left,k", "focus_prev", show=False),
+        Binding("down,right,j", "focus_next", show=False),
+        Binding("enter", "select", show=False),
+        Binding("escape,q", "quit", show=False),
+    ]
+
+    def __init__(
+        self,
+        items: list[SuggestionItem],
+        query: str,
+        mode: str,
+        missing_tokens: list[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self.items = items
+        self.search_query = query
+        self.mode = mode
+        self.missing_tokens = missing_tokens
+        self.copied_command: str | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Label(f"[bold #58a6ff]shix[/]  [italic #484f58]{self.mode}[/]", id="title-text")
+        yield Label(f"[#58a6ff]>[/] [bold #e6edf3]{self.search_query}[/]", id="query-text")
+
+        warning = Label("", id="warning")
+        if self.missing_tokens:
+            warning.update(f"[#d29922]no history for: {', '.join(self.missing_tokens)}[/]")
+            warning.add_class("visible")
+        yield warning
+
+        if self.items:
+            yield Label(f"[#484f58]{len(self.items)} results[/]", id="pills-label")
+            with PillsContainer(id="pills-area"):
+                for i, item in enumerate(self.items, 1):
+                    with ResultRow():
+                        yield Label(f"[#484f58]{i:>3}[/]", classes="pill-index")
+                        yield CommandPill(item.command)
+        else:
+            yield Label("[#d29922]No matches found. Try different keywords.[/]")
+
+        yield Label("[#58a6ff]arrows[/] [#484f58]navigate[/]  [#58a6ff]enter/click[/] [#484f58]copy[/]  [#58a6ff]esc[/] [#484f58]quit[/]", id="status-bar")
+
+    def on_mount(self) -> None:
+        pills = self.query(CommandPill)
+        if pills:
+            pills[0].focus()
+
+    def action_focus_next(self) -> None:
+        pills = self.query(CommandPill)
+        if not pills:
+            return
+        focused = self.screen.focused
+        current = -1
+        for i, p in enumerate(pills):
+            if p is focused:
+                current = i
+                break
+        nxt = current + 1 if current < len(pills) - 1 else 0
+        pills[nxt].focus(scroll_visible=False)
+        pills[nxt].scroll_visible(animate=False)
+
+    def action_focus_prev(self) -> None:
+        pills = self.query(CommandPill)
+        if not pills:
+            return
+        focused = self.screen.focused
+        current = -1
+        for i, p in enumerate(pills):
+            if p is focused:
+                current = i
+                break
+        prev = current - 1 if current > 0 else len(pills) - 1
+        pills[prev].focus(scroll_visible=False)
+        pills[prev].scroll_visible(animate=False)
+
+    def action_select(self) -> None:
+        focused = self.screen.focused
+        if isinstance(focused, CommandPill):
+            self._copy_command(focused.command)
+
+    def on_command_pill_selected(self, message: CommandPill.Selected) -> None:
+        self._copy_command(message.command)
+
+    def _copy_command(self, command: str) -> None:
+        self.copied_command = command
+        try:
+            import pyperclip
+            pyperclip.copy(command)
+        except Exception:
+            pass
+
+        status = self.query_one("#status-bar", Label)
+        status.update(f"[bold #ffffff]Copied:[/] {command}")
+        status.add_class("copied")
+        self.set_timer(0.4, self._exit_after_copy)
+
+    def _exit_after_copy(self) -> None:
+        self.exit(self.copied_command)
+
+
+def run_tui(
+    items: list[SuggestionItem],
+    query: str,
+    mode: str,
+    missing_tokens: list[str] | None = None,
+) -> str | None:
+    """Run the TUI and return the copied command (or None)."""
+    app = ShixApp(items, query, mode, missing_tokens)
+    return app.run()