DEV Community

Cover image for I built a "Lazy" AI Terminal Assistant because I hate memorizing flags
Abubakr Alsheikh
Abubakr Alsheikh

Posted on

I built a "Lazy" AI Terminal Assistant because I hate memorizing flags

#python #cli #productivity #opensource

The Problem: I love the terminal, but I hate the friction.

I live in the terminal. But let's be honest: doing simple things often feels like solving a puzzle.

  • Want to compress a folder of images? Time to look up ImageMagick flags.
  • Want to merge PDFs? Time to upload your private docs to some random "Free PDF Merger" website.
  • Want to rename 100 files? Time to write a throwaway Python script that you’ll delete 5 minutes later.

I wanted a tool that was Fast, Local, and unapologetically Lazy.

So, I built Max.

Meet Max CLI ⚡

Max is an open-source, modular command-line tool built with Python. It automates the mundane, local tasks we deal with daily, and it includes an AI Copilot to handle the rest.

Repo: github.com/Abubakr-Alsheikh/max-cli

Here is why it's different: It prioritizes local execution. When you compress images or order files, it happens on your machine. No cloud uploads. Speed is the priority.

What can it do? (The "Lazy" Features)

1. Smart Image Compression

Stop Googling compression algorithms. Max recursively scans folders, detects images, and optimizes them.

# Compress an entire folder of photos to JPEGs (Quality 80)
$ max images compress ./VacationPhotos --quality 80 --jpeg

# Resize a huge banner to 50% scale
$ max img compress banner.png --scale 50
Enter fullscreen mode Exit fullscreen mode

2. Sanity-Saving File Ordering

I constantly have folders full of scan.pdf, scan(1).pdf, document.docx. Max cleans this up by adding numerical ordering, with a safety-first "Dry Run" mode.

# Preview what will happen
$ max files order ./Downloads --dry-run
> [DRY RUN] Would rename 'report.pdf' -> '1_report.pdf'
> [DRY RUN] Would rename 'thesis.docx' -> '2_thesis.docx'
Enter fullscreen mode Exit fullscreen mode

3. The AI Copilot 🤖

This is the killer feature. Max uses the OpenAI SDK to translate Natural Language into CLI Arguments.

I didn't want a chatbot that just talks. I wanted a chatbot that does. Max reads its own documentation, understands the available tools, and constructs the command for you.

$ max ai ask "Combine all PDFs in the 'Contracts' folder"

# Max thinks... and suggests:
> max pdf merge ./Contracts
# Run this command? [y/N]:
Enter fullscreen mode Exit fullscreen mode

The Architecture (For the Nerds 🤓)

I didn't want a messy script. Max is built as a Modular Monolith using modern Python standards.

  • Framework: Typer (for that sweet CLI developer experience).
  • UI: Rich (for beautiful progress bars, tables, and error handling).
  • Engine:
    • Pillow for image logic.
    • PyMuPDF for PDF manipulation.
    • OpenAI for the intent classification layer.

The project structure separates Core Logic (pure Python) from the Interface (CLI commands), making it easy to test and scalable.

The Roadmap 🔮

Max is just getting started. I am actively working on:

  • 🎥 Local Media Engine: Wrapping ffmpeg to allow natural language video/audio conversion (max ai ask "Convert this MKV to MP4").
  • 🧠 Conversation Memory: A persistent chat mode so Max remembers context between commands.
  • 🎨 Generative AI: Creating assets locally (max create image "Cyberpunk city").
  • 🛡 Sandboxing: Scoped permissions so the AI can't touch system files without approval.

Contribute!

This is an open-source project, and I want it to be the ultimate developer companion.

If you hate memorizing flags or just want to see how to build a production-grade CLI in Python, check out the code.

⭐ Star the repo: github.com/Abubakr-Alsheikh/max-cli
🙌 Pull Requests are welcome!

Let me know in the comments: What is the one terminal command you always forget and wish an AI could handle for you?

Top comments (0)