matrixsh 0.1.0

MatrixShell: AI-augmented shell wrapper powered by MatrixLLM

Turn your terminal into a safe, AI-assisted shell

Features • Quick Start • Usage • How It Works • Configuration • Security • FAQ

---

Type normal commands as usual. Type natural language (any language) and MatrixShell suggests the right command, explains it, and runs it only with your confirmation.

/home/user/projects$ come posso cancellare questa cartella

╭─────────────────────────────────── MatrixLLM ───────────────────────────────────╮
│ Per cancellare la cartella, usa questo comando:                                 │
│                                                                                 │
│     rm -rf "BOT-MMORPG-AI-DEV"                                                  │
│                                                                                 │
│ Questo eliminerà tutti i file definitivamente.                                  │
╰─────────────────────────────────────────────────────────────────────────────────╯
Suggested command:
rm -rf "BOT-MMORPG-AI-DEV"
Risk: high

Execute it? (yes/no)

---

Features

• Natural Language to Commands — Describe what you want in plain English, Italian, Spanish, or any language
• Smart Command Detection — Automatically detects whether input is a command or natural language
• Risk Assessment — Every suggested command shows a risk level (low/medium/high)
• Hard Safety Limits — Dangerous operations (disk formatting, mass deletions) are blocked by default
• Cross-Platform — Works on Windows (CMD/PowerShell), macOS, and Linux (Bash)
• One-Command Setup — matrixsh setup handles everything automatically
• Secure Pairing — Local-only pairing mode ensures credentials stay on your machine
• Context-Aware — Maintains command history per directory for smarter suggestions

---

Requirements

• Python 3.9+
• MatrixLLM — AI gateway (auto-installed by matrixsh setup)
• uv or pipx — For installing Python CLI tools (recommended)

---

Installation

Option A: Using pipx (Recommended)

macOS / Linux / WSL

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install matrixsh

Windows PowerShell

python -m pip install --user pipx
python -m pipx ensurepath
pipx install matrixsh

Option B: Using uv

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install matrixsh

Option C: From Source (Dev Mode)

git clone https://github.com/agent-matrix/MatrixShell.git
cd MatrixShell
pip install -e .

---

Quick Start

1) One-Command Setup

matrixsh setup

What it does:

• Ensures MatrixLLM is installed (auto-installs via uv or pipx if missing)
• Starts MatrixLLM locally in pairing mode on 127.0.0.1:11435
• Prompts for a short pairing code (e.g., 483-921)
• Stores a token so future runs are automatic

2) Run MatrixShell

matrixsh

That's it! You're ready to go.

---

Usage

Normal Commands (Pass-Through)

matrixsh
/home/user$ ls -la
/home/user$ cd projects
/home/user/projects$ git status
/home/user/projects$ docker ps

MatrixShell runs these commands normally and prints output. No AI involved.

Natural Language Queries

Type what you want to do in any language:

English:

/home/user$ how can I find the biggest files here?

Italian:

C:\Users\rusla\temp> come posso cancellare questa cartella

Spanish:

/home/user$ cómo puedo ver los procesos que usan más memoria

MatrixShell detects natural language, asks MatrixLLM, and shows:

╭─────────────────────────────────── MatrixLLM ───────────────────────────────────╮
│ To find the biggest files, use this command which shows the top 20 largest:     │
╰─────────────────────────────────────────────────────────────────────────────────╯
Suggested command:
du -ah . | sort -hr | head -n 20
Risk: low

Execute it? (yes/no)

Handling "Command Not Found"

If you type a word that isn't a command:

/home/user$ hello
bash: hello: command not found

MatrixShell automatically switches to AI help and may suggest:

echo "Hello!"

Shell Modes

Force a specific shell mode:

matrixsh --mode powershell   # Windows PowerShell
matrixsh --mode cmd          # Windows CMD
matrixsh --mode bash         # Linux/macOS Bash
matrixsh --mode auto         # Auto-detect (default)

Exit

/exit

---

How It Works

Step-by-Step Flow

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              MatrixShell Flow                                   │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   User Input                                                                    │
│       │                                                                         │
│       ▼                                                                         │
│   ┌───────────────────┐                                                         │
│   │ Is it a command?  │──── Yes ────▶ Execute directly ──▶ Show output          │
│   └───────────────────┘                                                         │
│       │ No / Failed                                                             │
│       ▼                                                                         │
│   ┌───────────────────┐                                                         │
│   │ Natural language  │                                                         │
│   │ or cmd not found  │                                                         │
│   └───────────────────┘                                                         │
│       │                                                                         │
│       ▼                                                                         │
│   ┌───────────────────┐      ┌─────────────────────────────────┐                │
│   │ Gather context:   │      │ MatrixLLM responds with:        │                │
│   │ • OS + shell      │─────▶│ • explanation                   │                │
│   │ • current dir     │      │ • suggested command             │                │
│   │ • file list       │      │ • risk level (low/medium/high)  │                │
│   │ • recent history  │      └─────────────────────────────────┘                │
│   └───────────────────┘                    │                                    │
│                                            ▼                                    │
│                               ┌───────────────────────┐                         │
│                               │ Show suggestion       │                         │
│                               │ Ask: Execute? (y/n)   │                         │
│                               └───────────────────────┘                         │
│                                            │                                    │
│                          ┌─────────────────┴─────────────────┐                  │
│                          │                                   │                  │
│                         Yes                                 No                  │
│                          │                                   │                  │
│                          ▼                                   ▼                  │
│                   ┌─────────────┐                    ┌──────────────┐           │
│                   │ Check       │                    │ Cancelled.   │           │
│                   │ denylist    │                    └──────────────┘           │
│                   └─────────────┘                                               │
│                          │                                                      │
│              ┌───────────┴───────────┐                                          │
│              │                       │                                          │
│           Allowed                 Denied                                        │
│              │                       │                                          │
│              ▼                       ▼                                          │
│       ┌─────────────┐      ┌─────────────────────┐                              │
│       │ Execute     │      │ Refusing to execute │                              │
│       │ Show output │      │ (safety denylist)   │                              │
│       └─────────────┘      └─────────────────────┘                              │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

1) Smart Wrapper Shell

MatrixShell is not a plugin that modifies CMD/PowerShell/bash. Instead, it runs its own interactive loop:

• Shows a normal prompt (like C:\...> or /home/...$)
• Reads what you type
• Decides what to do next

2) Tries Normal Commands First

If you type a real command (dir, ls, cd, git status, python --version), MatrixShell executes it using the selected shell mode:

• Windows: PowerShell by default (or CMD if you choose)
• Linux/macOS/WSL: Bash

If the command succeeds, it just prints output. No AI needed.

3) Detects Natural Language or "Command Not Found"

If you type something like:

• "come posso cancellare questa cartella?"
• "how do I find big files?"
• "why is port 11435 busy?"

Or you type a command that fails with "command not found", MatrixShell switches into AI fallback mode.

4) Sends Context to MatrixLLM

MatrixShell gathers helpful context:

• OS + shell mode
• Current directory
• List of files/folders in the directory
• Your last few messages (history per directory)

Then it calls MatrixLLM's endpoint: POST /v1/chat/completions

MatrixLLM responds with structured JSON:

{
  "explanation": "...",
  "command": "...",
  "risk": "low|medium|high"
}

5) Shows Suggestion and Asks Permission

MatrixShell prints:

• Explanation (in your language)
• Suggested command
• Risk level

Then asks:

Execute it? (yes/no)

Only if you answer yes, it runs the command.

---

Configuration

Config File Location

Platform	Path
Linux/macOS/WSL	~/.config/matrixsh/config.json
Windows	%APPDATA%\matrixsh\config.json

Config File Format

{
  "base_url": "http://localhost:11435/v1",
  "api_key": "",
  "token": "mtx_abc123...",
  "model": "deepseek-r1",
  "timeout_s": 120
}

Environment Variables

Environment variables override config file settings:

Variable	Description
MATRIXLLM_BASE_URL	Gateway URL
MATRIXSH_BASE_URL	Alternative to above
MATRIXLLM_API_KEY	API key for authentication
MATRIXSH_API_KEY	Alternative to above
MATRIXSH_TOKEN	Pairing token (takes priority)
MATRIXLLM_MODEL	Model name
MATRIXSH_MODEL	Alternative to above

Priority Order

1. Command-line arguments (--url, --key, etc.)
2. Environment variables
3. Config file
4. Built-in defaults

---

Commands Reference

Command	Description
matrixsh	Start interactive shell
matrixsh setup	One-command setup (install, start, pair)
matrixsh install	Write config and test gateway connection
/exit or /quit	Exit MatrixShell (inside the shell)

Setup Options

matrixsh setup --port 8080           # Custom port
matrixsh setup --model gpt-4         # Custom model
matrixsh setup --url http://...      # Custom URL (local only)

Install Options

matrixsh install --url https://api.example.com/v1 --key "sk-..."
matrixsh install --token "mtx_..."
matrixsh install --model gpt-4

Runtime Options

matrixsh --no-healthcheck            # Skip health check
matrixsh --stream                    # Enable streaming
matrixsh --url ... --model ... --key ...  # Override for session

---

Security

Confirmation Before Execution

MatrixShell always asks:

Execute it? (yes/no)

Nothing runs without your explicit approval.

Hard Denylist

MatrixShell refuses to execute system-critical commands, even if you type "yes":

Platform	Blocked Commands
Windows	format, diskpart, bcdedit, registry modifications
Linux/macOS	mkfs.*, dd if=..., fdisk, parted
All	shutdown, reboot, init 0

You can still copy/paste manually if you truly intend it.

Pairing Mode Security

• Local-Only — Pairing only works with localhost, 127.0.0.1, or ::1
• One-Time Code — 6-digit codes expire quickly
• Token-Based Auth — After pairing, a token (mtx_...) is saved locally
• No Network Exposure — Gateway binds to 127.0.0.1 by default

Remote Gateways

For remote MatrixLLM instances, pairing is disabled for security. Use API keys instead:

matrixsh install --url https://api.example.com/v1 --key "sk-..."

---

What MatrixShell Sends to the Model

MatrixShell only sends lightweight context:

• Current directory path
• A list of file/folder names (not file contents)
• Your input and short local history

It does not read or upload your files unless you explicitly command it to (e.g., cat file.txt).

---

Troubleshooting

MatrixLLM Not Running

MatrixLLM not running. Start it now? [Y/n]

Press Enter to start automatically, or run:

matrixsh setup

Unauthorized (401)

Unauthorized (401). MatrixLLM requires credentials.

Solutions:

• Local: matrixsh setup
• Remote: matrixsh install --key "sk-..."

Pairing Not Enabled

Pairing is not enabled on this MatrixLLM instance.

Restart MatrixLLM with pairing:

matrixllm start --auth pairing --host 127.0.0.1 --port 11435

WSL Can't Reach localhost

In most WSL2 setups, localhost works. If not:

• Try http://127.0.0.1:11435/v1
• Verify Windows firewall rules
• Ensure MatrixLLM is bound correctly

---

Demo

Run the fake terminal demo:

make demo

Or record a real demo with asciinema:

bash demo/record_asciinema.sh

See docs/DEMO.md for detailed instructions.

---

Documentation

• FAQ — Frequently asked questions
• Demo Guide — How to record demos

---

License

Apache License 2.0 — See LICENSE for details.

---

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

MatrixShell — Your terminal, augmented with AI.