Modux

Modux is a cross-platform AI terminal assistant that lets you interact with your computer using natural language.

Instead of remembering operating-system-specific commands, you can simply tell Modux what you want to do.

For example:

Modux > create a folder named projects

Modux understands the request and performs the appropriate operation for your operating system.

Modux is designed to work across:

• Windows
• Linux
• macOS

---

Features

• 🤖 AI-powered terminal assistant
• 💬 Natural-language interaction
• 🖥️ Windows, Linux and macOS support
• 📁 File and directory operations
• 🔍 Code inspection
• 🛠️ AI-assisted code fixing
• ▶️ Python and Bash file execution
• 🐛 Automatic error analysis
• 📊 Project understanding
• 💾 Secure API-key storage
• ✅ Confirmation before system actions
• 🧪 Automated tests

---

How Modux Works

Modux separates the AI from the operating-system execution layer.

User request
     │
     ▼
   Modux
     │
     ▼
   Groq AI
     │
     ▼
  User intent
     │
     ▼
Modux execution layer
     │
 ┌───┼────┐
 ▼   ▼    ▼
Win Linux macOS
 │   │    │
 ▼   ▼    ▼
Native Python operations

The user does not need to choose between CMD, PowerShell or Bash for supported operations.

---

Requirements

Before installing Modux, you need:

• Python 3.10 or newer
• Internet connection
• A Groq account
• A Groq API key

Check your Python installation:

python --version

You should see Python 3.10 or newer.

---

Installation

Recommended: pipx

pipx is recommended because Modux is a command-line application.

Windows

Install pipx:

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

Close and reopen PowerShell after running ensurepath.

Then install Modux:

pipx install modux

Linux

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

Restart your terminal, then:

pipx install modux

macOS

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

Restart your terminal, then:

pipx install modux

---

Alternative: pip

You can also install Modux directly using pip:

python -m pip install modux

After installation, verify it:

modux

---

First-Time Setup

After installing Modux, simply run:

modux

If Modux has not been configured, it will automatically ask whether you want to configure it.

You can also explicitly start setup:

modux setup

You will see something similar to:

================================
          MODUX SETUP
================================

Modux requires a Groq API key.

1. Open:
   https://console.groq.com/keys

2. Create a Groq API key.

3. Paste the key below.

Groq API Key:

Paste your API key and press Enter.

The API key is not displayed while you type it.

---

Getting a Groq API Key

You need your own Groq API key to use Modux.

Open:

https://console.groq.com/keys

Then:

1. Sign in to your Groq account.
2. Create a new API key.
3. Copy the key.
4. Run:

modux setup

5. Paste the key when Modux asks for it.

Your API key is stored using the operating system's credential storage through Python Keyring.

Never publish your API key on GitHub.

---

API Key Management

Configure or change your API key

modux setup

This allows you to add a new key or replace the existing key.

---

Check configuration

modux config

Example:

Groq API key: configured

Modux never displays your actual API key.

---

Remove your stored API key

modux logout

This removes the API key stored by Modux.

---

Starting Modux

After installation and setup:

modux

You will see:

================================
          MODUX 0.1.0
================================
Operating System: Windows

Type 'help' for commands.

Modux >

---

Modux Commands

Exit Modux

Modux > exit

---

Show files

Modux > show my files

Modux automatically performs the appropriate operation for your operating system.

---

Show current directory

Modux > show my current directory

---

Create a directory

Modux > create a folder named projects

---

Create a file

Modux > create a file named hello.txt

---

Delete a file

Modux > delete hello.txt

Modux asks for confirmation before performing the operation.

---

Copy a file

Modux > copy app.py to backup.py

---

Move a file

Modux > move app.py to backup/app.py

---

Check disk space

Modux > check disk space

---

System information

Modux > what operating system am I using

---

Clean temporary files

Modux > clean temporary files

Modux uses the appropriate temporary directory for the operating system.

---

Ping a host

Modux > ping google.com

---

Find an installed program

Modux > where is git installed

---

Open a website

Modux > open https://github.com

---

Code Assistance

Modux can also work with source code.

Inspect a file

Modux > inspect test.py

Modux reads the file and explains:

• What the code does
• Possible problems
• Possible improvements

---

Fix a file

Modux > fix test.py

Modux generates a corrected version of the code and shows it before making changes.

You must explicitly confirm the changes.

Apply these changes? [y/N]:

---

Run a Python file

Modux > run test.py

Modux executes the Python program and displays its output.

If the program fails, Modux automatically analyzes the error.

Example:

Program failed.

Error:
ZeroDivisionError: division by zero

Modux Analysis:

The program attempted to divide by zero...

---

Run a Bash script

Modux > run script.sh

Bash must be installed and available on the system.

---

Understand a Project

From inside a project directory:

Modux > understand this project

Modux scans the project files and provides an overview of:

• Project structure
• Important files
• What files do
• Technologies detected from the source
• How components connect
• Possible improvements

Generated directories such as:

.git
venv
.venv
__pycache__
node_modules

are excluded from project analysis.

---

Confirmation System

Modux does not silently perform supported system actions.

For example:

Modux > create a folder named test

Action:
CREATE_DIRECTORY

Arguments:
  name: test

Execute this action? [y/N]:

You must confirm the action.

Use:

y

to execute it.

Use:

n

or simply press Enter to cancel it.

---

Supported Operating Systems

Windows

Modux automatically detects Windows and uses Windows-compatible behavior internally.

Users do not need to choose CMD or PowerShell.

Linux

Modux detects Linux and uses Linux-compatible behavior.

macOS

Modux detects macOS and uses macOS-compatible behavior.

The goal is for the Modux user experience to remain the same across all three platforms.

---

Security

Modux is designed to avoid exposing operating-system shell syntax to the AI for supported operations.

The AI first identifies the user's intent.

For example:

create a folder named test

becomes an internal intent:

CREATE_DIRECTORY

Modux then performs that operation itself.

This is safer than blindly executing arbitrary commands generated by an AI model.

API Keys

Your Groq API key belongs to your own Groq account.

Modux does not provide a shared API key.

Never:

• Put your API key in source code
• Commit your API key to Git
• Upload your API key to GitHub
• Share your API key publicly

Use:

modux setup

to configure your key.

---

Troubleshooting

modux is not recognized

Try reinstalling:

python -m pip install modux

If using pipx:

pipx install modux

Then restart your terminal.

---

Modux says the API key is not configured

Run:

modux setup

Then enter your Groq API key.

---

Check whether the key is configured

Run:

modux config

You should see:

Groq API key: configured

---

Modux cannot connect to Groq

Check:

1. Your internet connection
2. Your Groq account
3. Your API key
4. Whether your Groq API key is still active

Run:

modux setup

to replace the stored key.

---

Developer Setup

If you want to work on the Modux source code:

Clone the repository:

git clone https://github.com/krishpatel-acc/modux.git

Enter the project:

cd modux

Install in editable mode:

python -m pip install -e .

Install testing tools:

python -m pip install pytest

Run the test suite:

python -m pytest

Expected result:

13 passed

---

Project Structure

modux/
│
├── src/
│   └── modux/
│       ├── __init__.py
│       ├── ai.py
│       ├── cli.py
│       ├── config.py
│       ├── executor.py
│       └── project.py
│
├── tests/
│   └── test_modux.py
│
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

---

Development

Install the project:

python -m pip install -e .

Run Modux:

modux

Run tests:

python -m pytest

Build the package:

python -m pip install build
python -m build

The generated packages will appear inside:

dist/

---

GitHub

Source code:

https://github.com/krishpatel-acc/modux

Modux is open source and welcomes contributions.

---

License

Modux is released under the MIT License.

See LICENSE for the complete license.