pip install ai-linux-assistant

Talk to your terminal. It talks back safely.

An AI-powered natural-language Linux command-line assistant. Type what you want 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.

Python package CLI, not a web app No login, no database
Install now → See how it works
bash — ai

what it does

Plain English in, the right command out.

Built for people who know what they want to do but don't want to memorize flags.

>_

Single-shot

Scriptable one-liners: ai "find the largest file in this folder" and it just runs.

⟲

Interactive mode

A live session that remembers context across turns, including "now sort them by size" and undo.

✓

Independent safety check

A separate engine analyzes the full command string before anything runs — the AI can't talk its way past it.

◧

Explains before it runs

--explain shows you exactly what a command does before you commit to it.

↺

Learns from failure

Captures stdout/stderr/exit code, analyzes what went wrong, and suggests the next step.

▤

History & undo

ai --history 20 replays your recent commands; interactive mode supports stepping back.

architecture

Four stages, one pipeline.

Natural language goes in one end; a verified, explained result comes out the other. Nothing skips the safety stage.

01 · NLP
NLPEngine
Understands intent, drafts a command or multi-step plan, proposes an advisory risk hint
→
02 · Safety
SafetyEngine
Independent static analysis of pipes, redirects, sudo, chained operators
ALLOWCONFIRMBLOCK
→
03 · Execute
CommandExecutor
Runs the approved command, captures output, analyzes the result
→
04 · Context
ConversationContext
Feeds follow-ups like "why did that fail?" or "undo that"

The AI's own risk hint can only escalate a verdict, never soften one — only the SafetyEngine has final say.

the safety layer

Three verdicts. No exceptions.

Every command is classified before it ever touches your shell.

ALLOW ls -la · df -h · cat file.txt

Read-only commands run automatically — nothing to confirm.

CONFIRM mkdir new/ · mv a b · chmod +x run.sh

Anything that changes state asks first, in an interactive terminal.

BLOCK rm -rf / · curl x | bash · fork bombs

Catastrophic commands are refused outright — --yes can't bypass a BLOCK.

get it running

Install it in under a minute.

Not yet published to PyPI in every environment — if a step fails, build locally with pip install -e . from the repo instead.

// quickstart

# 1. create and activate a virtual environment
python3 -m venv ~/ai-test
source ~/ai-test/bin/activate

# 2. install the assistant
python -m pip install ai-linux-assistant

# 3. install the AI SDK it talks to
pip install google-genai

# 4. set your API key
export GEMINI_API_KEY="YOUR_API_KEY_HERE"

# 5. run it
ai "find the largest file in this folder"

using it

Single-shot or interactive.

Scriptable

ai "show my disk usage"
ai --explain "find . -type f -mtime +7 -delete"
ai --history 20

Interactive session

$ ai
you> find the largest file
you> now sort them by size
you> undo
you> exit

under the hood

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 executor/ Linux Execution + Smart Features — subprocess execution, output analysis, suggestions, multi-step runs, history cli.py CLI + Packaging — terminal interface tying it together tests/ unit tests per module + end-to-end integration tests