ai-linux-assistant

An AI-powered natural-language Linux command-line assistant. Type what you want to do in plain English; it figures out the Bash command, explains it, checks whether it's safe to run automatically, executes it, and explains the result.

ai "find the largest file in this folder"
ai "show my disk usage"
ai "create a folder called projects"
ai "why is my python command failing?"

Not a web app, no Firebase, no login system, no database — a Python package you run from your own terminal.

Install

pip install ai-linux-assistant
export ANTHROPIC_API_KEY=your-key-here

(Not yet published to PyPI — see pyproject.toml to build/install locally with pip install -e ..)

Usage

Single-shot (scriptable):

ai "find the largest file in this folder"
ai --explain "find . -type f -mtime +7 -delete"
ai --history 20

Interactive (remembers context across turns, supports undo):

$ ai
you> find the largest file
  $ find . -type f -exec du -h {} + | sort -rh | head -n 1
  ...
you> now sort them by size
you> undo
you> exit

How it works

natural language
      │
      ▼
NLPEngine            understands intent, generates a command (or a
(AI + NLP)            multi-step plan), explains it, proposes an
                       advisory risk_hint
      │
      ▼
SafetyEngine          independent static analysis of the full command
(Safety/Permission)    string (pipes, redirects, sudo, chained operators,
                        etc). Only this module decides ALLOW / CONFIRM /
                        BLOCK — the AI's own risk_hint can escalate a
                        verdict but never soften one
      │
      ▼
CommandExecutor        runs the approved command, captures stdout/
(Linux Execution)       stderr/exit code, analyzes the result, and
                        suggests a next step on failure
      │
      ▼
back into NLPEngine's ConversationContext, so follow-up turns
("why did that fail?", "undo that") have something to reason about

Read-only commands (ls, pwd, df, cat, grep, ...) run automatically. Commands that change something (mkdir, rm, mv, chmod, sudo, package installs, ...) ask for confirmation first. Catastrophic commands (rm -rf /, fork bombs, raw disk writes, piping a remote script straight into bash, ...) are refused outright.

Project layout

ai_linux_assistant/
    nlp/        AI + Natural Language — intent, command generation,
                explanations, context, master prompts
    safety/     Safety/Permission Engine — command risk analysis,
                confirmation system, dangerous-command detection
                (core/ is Member 2's real submitted engine; engine.py
                adapts it into the app's ALLOW/CONFIRM/BLOCK contract)
    executor/   Linux Execution + Smart Features — subprocess execution,
                output analysis, suggestions, multi-step runs, history
    cli.py      CLI + Packaging — terminal interface tying the above
                together
tests/          unit tests per module + end-to-end integration tests

See INTEGRATION.md for how each module's work was combined and what's still outstanding.

Development

pip install -e ".[dev]"
python3 -m pytest tests/ -v

Development and testing

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python3 -m pytest -v

CLI

ai --version
ai --help
ai "show my disk usage"
ai --explain "ls -la"
ai --history 20

Modifying commands require confirmation in an interactive terminal. --yes is an explicit opt-in for automation; critical BLOCK decisions are never bypassed.

Build package

python3 -m pip install --upgrade build
python3 -m build

The generated wheel and source distribution in dist/ can be tested locally before any PyPI upload.