matrixsh 0.1.0

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

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:

Priority Order

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

Commands Reference

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":

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.