@austinthesing/magic-shell 0.2.11 → 0.2.14

package/README.md

@@ -7,7 +7,8 @@ Magic Shell is an open-source CLI tool that translates plain English (or any nat
 ## Features
 
 - **Natural Language Translation**: Describe what you want to do in plain English
-- **Multiple AI Providers**: OpenCode Zen (with free models!) and OpenRouter
+- **Multiple AI Providers**: OpenCode Zen (with free models!), OpenRouter, and custom models (LM Studio, Ollama, OpenAI-compatible)
+- **Custom Model Support**: Add your own local or remote models with secure API key storage
 - **Project Context Aware**: Opt-in detection of package.json scripts, Makefile targets, etc.
 - **Interactive TUI Mode**: Full-featured terminal interface with themes
 - **Command Safety Analysis**: Multi-level safety checks before executing commands
@@ -88,23 +89,26 @@ mshell
 
 ### Command Reference
 
-| Command | Description |
-|---------|-------------|
-| `msh <query>` | Translate query to command and print it |
-| `msh -x <query>` | Translate and execute the command |
-| `msh -n <query>` | Dry run - show command with safety analysis |
-| `mshell` | Launch interactive TUI mode |
-| `msh --setup` | Configure API keys and provider |
-| `msh --models` | List available models |
-| `msh --model <id>` | Set default model |
-| `msh --provider <name>` | Set provider (opencode-zen or openrouter) |
-| `msh --themes` | List available themes |
-| `msh --theme <name>` | Set color theme |
-| `msh --repo-context` | Enable project context detection |
-| `msh -r <query>` | Use project context for single query |
-| `msh --version` | Show version |
-| `msh --check-update` | Check for updates |
-| `msh --help` | Show help |
+| Command                   | Description                                 |
+| ------------------------- | ------------------------------------------- |
+| `msh <query>`             | Translate query to command and print it     |
+| `msh -x <query>`          | Translate and execute the command           |
+| `msh -n <query>`          | Dry run - show command with safety analysis |
+| `mshell`                  | Launch interactive TUI mode                 |
+| `msh --setup`             | Configure API keys and provider             |
+| `msh --models`            | List available models                       |
+| `msh --model <id>`        | Set default model (including custom models) |
+| `msh --add-model`         | Add custom model (LM Studio, Ollama, etc.)  |
+| `msh --list-custom`       | List custom models                          |
+| `msh --remove-model <id>` | Remove custom model                         |
+| `msh --provider <name>`   | Set provider (opencode-zen or openrouter)   |
+| `msh --themes`            | List available themes                       |
+| `msh --theme <name>`      | Set color theme                             |
+| `msh --repo-context`      | Enable project context detection            |
+| `msh -r <query>`          | Use project context for single query        |
+| `msh --version`           | Show version                                |
+| `msh --check-update`      | Check for updates                           |
+| `msh --help`              | Show help                                   |
 
 ### Examples
 
@@ -139,21 +143,21 @@ Launch with `mshell` for a full interactive experience.
 
 All shortcuts use the `Ctrl+X` chord (press Ctrl+X, then the key):
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl+X P` | Open command palette |
-| `Ctrl+X M` | Change model |
-| `Ctrl+X S` | Switch provider |
-| `Ctrl+X D` | Toggle dry-run mode |
-| `Ctrl+X T` | Change theme |
+| Shortcut   | Action                 |
+| ---------- | ---------------------- |
+| `Ctrl+X P` | Open command palette   |
+| `Ctrl+X M` | Change model           |
+| `Ctrl+X S` | Switch provider        |
+| `Ctrl+X D` | Toggle dry-run mode    |
+| `Ctrl+X T` | Change theme           |
 | `Ctrl+X R` | Toggle project context |
-| `Ctrl+X H` | Show history |
-| `Ctrl+X C` | Show config |
-| `Ctrl+X L` | Clear output |
-| `Ctrl+X ?` | Show help |
-| `Ctrl+X Q` | Exit |
-| `Ctrl+C` | Exit / Cancel |
-| `Esc` | Close dialogs |
+| `Ctrl+X H` | Show history           |
+| `Ctrl+X C` | Show config            |
+| `Ctrl+X L` | Clear output           |
+| `Ctrl+X ?` | Show help              |
+| `Ctrl+X Q` | Exit                   |
+| `Ctrl+C`   | Exit / Cancel          |
+| `Esc`      | Close dialogs          |
 
 ### Direct Commands in TUI
 
@@ -174,15 +178,21 @@ You can also type commands directly in the TUI:
 OpenCode Zen provides curated models optimized for coding tasks, including **free models**.
 
 **Free Models:**
+
 - `big-pickle` - Stealth model (default)
-- `grok-code` - xAI's Grok Code Fast 1
 - `glm-4.7` - GLM 4.7
+- `minimax-m2.1` - MiniMax's capable model
+- `kimi-k2.5` - Moonshot's latest model
 
 **Premium Models:**
+
 - Claude Sonnet 4.5, Claude Opus 4.5
+- Claude Haiku 4.5
 - Kimi K2, Kimi K2 Thinking
 - Qwen3 Coder 480B
 - GLM 4.6
+- Gemini 3 Pro, Gemini 3 Flash
+- GPT 5.2, GPT 5.2 Codex, GPT 5.1 series
 - And more...
 
 Get your API key at: https://opencode.ai/auth
@@ -192,29 +202,71 @@ Get your API key at: https://opencode.ai/auth
 Access to a wide variety of models from different providers.
 
 **Free Models:**
+
 - MiMo V2 Flash
 - DeepSeek V3
 
 **Premium Models:**
+
 - Claude Sonnet 4.5, Claude Opus 4.5
+- Claude Haiku 4.5
 - DeepSeek R1
 - GLM 4.7
+- Gemini 2.5 Pro, Gemini 2.5 Flash (stable until June 2026)
 - And many more...
 
 Get your API key at: https://openrouter.ai/keys
 
+### Custom Models
+
+Magic Shell supports custom models for local or remote OpenAI-compatible endpoints, including:
+
+- **LM Studio** - Run models locally
+- **Ollama** - Local model management
+- **Any OpenAI-compatible API** - Self-hosted or third-party endpoints
+
+**Adding a Custom Model:**
+
+```bash
+# Interactive setup
+msh --add-model
+
+# You'll be prompted for:
+# - Model ID (for referencing, e.g., "my-local-llama")
+# - Display name (e.g., "Local Llama 3.2")
+# - API model ID (sent to server, e.g., "llama-3.2-3b")
+# - Base URL (e.g., "http://localhost:1234/v1")
+# - API key (optional, stored securely in keychain)
+# - Category (fast/smart/reasoning)
+```
+
+**Managing Custom Models:**
+
+```bash
+# List all custom models
+msh --list-custom
+
+# Set a custom model as default
+msh --model my-local-llama
+
+# Remove a custom model
+msh --remove-model my-local-llama
+```
+
+Custom model API keys are securely stored in your system keychain, just like provider API keys.
+
 ## Safety System
 
 Magic Shell includes a comprehensive safety analysis system that categorizes commands by risk level:
 
 ### Severity Levels
 
-| Level | Description | Examples |
-|-------|-------------|----------|
+| Level        | Description                            | Examples                                |
+| ------------ | -------------------------------------- | --------------------------------------- |
 | **Critical** | Could cause irreversible system damage | `rm -rf /`, fork bombs, disk overwrites |
-| **High** | Significant changes or data loss risk | `sudo rm`, `kill -9 -1`, `shutdown` |
-| **Medium** | Requires elevated privileges | `sudo`, `chmod`, package removal |
-| **Low** | Worth reviewing | `git checkout`, `npm install` |
+| **High**     | Significant changes or data loss risk  | `sudo rm`, `kill -9 -1`, `shutdown`     |
+| **Medium**   | Requires elevated privileges           | `sudo`, `chmod`, package removal        |
+| **Low**      | Worth reviewing                        | `git checkout`, `npm install`           |
 
 ### Safety Levels
 
@@ -227,6 +279,7 @@ Configure your preferred safety level:
 ### Blocked Commands
 
 Certain dangerous patterns are always blocked:
+
 - Fork bombs
 - Direct disk writes (`> /dev/sda`)
 - Filesystem formatting (`mkfs`)
@@ -247,17 +300,27 @@ Configuration is stored in `~/.magic-shell/config.json`.
   "repoContext": false,
   "theme": "opencode",
   "blockedCommands": [...],
-  "confirmedDangerousPatterns": [...]
+  "confirmedDangerousPatterns": [...],
+  "customModels": [
+    {
+      "id": "my-local-llama",
+      "name": "Local Llama 3.2",
+      "modelId": "llama-3.2-3b",
+      "baseUrl": "http://localhost:1234/v1",
+      "contextLength": 128000,
+      "category": "smart"
+    }
+  ]
 }
 ```
 
 ### Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `OPENCODE_ZEN_API_KEY` | API key for OpenCode Zen |
-| `OPENROUTER_API_KEY` | API key for OpenRouter |
-| `DEBUG_API=1` | Enable API response debugging |
+| Variable               | Description                   |
+| ---------------------- | ----------------------------- |
+| `OPENCODE_ZEN_API_KEY` | API key for OpenCode Zen      |
+| `OPENROUTER_API_KEY`   | API key for OpenRouter        |
+| `DEBUG_API=1`          | Enable API response debugging |
 
 ## Themes
 
@@ -273,6 +336,7 @@ Magic Shell includes 8 beautiful themes:
 - `matrix` - Classic green terminal
 
 Change themes:
+
 ```bash
 # CLI
 msh --theme tokyonight
@@ -295,12 +359,12 @@ Magic Shell automatically detects and adapts to your shell:
 
 ## Platform Support
 
-| Platform | Shell Detection | Keychain Storage |
-|----------|-----------------|------------------|
-| macOS | Full | macOS Keychain |
-| Linux | Full | libsecret (secret-tool) |
-| Windows | Full | Credential Manager |
-| WSL | Full (detected) | libsecret |
+| Platform | Shell Detection | Keychain Storage        |
+| -------- | --------------- | ----------------------- |
+| macOS    | Full            | macOS Keychain          |
+| Linux    | Full            | libsecret (secret-tool) |
+| Windows  | Full            | Credential Manager      |
+| WSL      | Full (detected) | libsecret               |
 
 ## Development
 
@@ -351,18 +415,14 @@ src/
    ```json
    {
      "name": "@austinthesing/magic-shell",
-     "version": "0.2.2",
+     "version": "0.2.13",
      "description": "Natural language to terminal commands with safety features",
      "main": "dist/index.js",
      "bin": {
-       "msh": "./dist/index.js",
-       "mshell": "./dist/tui.js"
+       "msh": "dist/index.js",
+       "mshell": "dist/tui.js"
      },
-     "files": [
-       "dist",
-       "README.md",
-       "LICENSE"
-     ],
+     "files": ["dist", "README.md", "LICENSE"],
      "repository": {
        "type": "git",
        "url": "https://github.com/austin-thesing/magic-shell.git"
@@ -371,37 +431,30 @@ src/
      "bugs": {
        "url": "https://github.com/austin-thesing/magic-shell/issues"
      },
-     "keywords": [
-       "cli",
-       "terminal",
-       "natural-language",
-       "shell",
-       "ai",
-       "openrouter",
-       "opencode",
-       "command-line"
-     ],
+     "keywords": ["cli", "terminal", "natural-language", "shell", "ai", "openrouter", "opencode", "command-line"],
      "author": "Your Name <your@email.com>",
      "license": "MIT"
    }
    ```
 
 2. **Build the project:**
+
    ```bash
    bun run build
    ```
 
 3. **Test locally before publishing:**
+
    ```bash
    # Create a tarball
    npm pack
-   
+
    # Install it globally to test
    npm install -g ./magic-shell-0.1.0.tgz
-   
+
    # Test it works
    msh --help
-   
+
    # Uninstall test version
    npm uninstall -g magic-shell
    ```
@@ -419,18 +472,20 @@ npm publish --access public
 ### Releasing New Versions
 
 1. **Update version** (follows [semver](https://semver.org/)):
+
    ```bash
    # Patch release (bug fixes): 0.1.0 -> 0.1.1
    npm version patch
-   
+
    # Minor release (new features): 0.1.0 -> 0.2.0
    npm version minor
-   
+
    # Major release (breaking changes): 0.1.0 -> 1.0.0
    npm version major
    ```
 
 2. **Push tags to GitHub:**
+
    ```bash
    git push origin main --tags
    ```
@@ -450,29 +505,29 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      
+
       - uses: oven-sh/setup-bun@v1
         with:
           bun-version: latest
-      
+
       - name: Install dependencies
         run: bun install
-      
+
       - name: Build
         run: bun run build
-      
+
       - name: Publish to npm
         run: npm publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v1
         with:
@@ -480,6 +535,7 @@ jobs:
 ```
 
 Add your npm token to GitHub:
+
 1. Generate token at https://www.npmjs.com/settings/tokens (use "Automation" type)
 2. Add to repository secrets as `NPM_TOKEN`