D.01
One catalog, three front ends
Every action is described once. The command line, the dashboard and the agent are three views of the same catalog running the same operations, so a new action appears in all three.
Open source · v1.2.0 on PyPI · docs on GitHub Pages
Max CLI: Terminal Assistant
A terminal assistant that turns media, PDF, image, download and file chores into short commands, and runs them for you from plain words.
01 // Problem
Compressing a video, merging PDFs or tidying a downloads folder each means a different tool and a page of flags. Max puts those jobs behind one command, max, with sane defaults, lets you ask for them in plain words, and keeps an undo for anything that touches your files.
- commands in the README
- 73
- CI jobs per push
- 14
- test modules
- 92
- commits
- 417
02 // Architecture
- L1core/catalog/One description per action: its parameters, defaults, danger level and batch rules. The CLI, the dashboard and the agent all read it, so they offer the same options.
- L2core/operations/ + engines/The work behind each action, over engines for FFmpeg, PDF, images, AI providers, downloads and the background task queue.
- L3core/agent/The AI agent: Max's own commands as its tools, a path scope it cannot leave, plans shown before multi-step work, and batch and parallel runs.
- L4interface/Typer command groups for video, audio, images, PDF, grab, files, AI, queue, tools, config and plugins, plus a Textual dashboard that a bare
maxopens. - L5common/ + plugins/Shared plumbing (atomic writes, file locks, the undo log) and a loader for drop-in plugin files.
03 // Key_Decisions
D.02
The agent only uses Max
max "sort my Music folder by artist" plans with Max's own commands and nothing else. It stays inside the folders you name, asks before it moves, overwrites or deletes, and max ai undo puts back its last request.
D.03
File operations can be undone
Each command that renames, moves or deletes files writes its operations as one group in an undo log. The log keeps 50 groups for 30 days.
D.04
A main model and a fallback
You pick a main AI and a fallback from OpenAI, OpenRouter, Gemini or a local Ollama model. When the main one fails, Max switches to the fallback.
D.05
Tested where it runs
CI runs Pytest on Ubuntu, macOS and Windows across Python 3.9 to 3.12, holds type errors under a mypy baseline that may not rise, and builds the package. Separate workflows publish the docs and release to PyPI.
04 // From_The_Source
05 // Stack
- Python
- Typer
- Textual
- FFmpeg
- OpenAI SDK
- Pytest