MLX developer tooling

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Classification: an authored tool. It is a small working personal utility, not a product. It also includes a curated model-download setup. It was built on 2026-10-04 in one Claude Code session at the studio’s request ("create a tool so my most advanced MLX offline coding model can be called… say show the top running processes and mlx-cli enters top"). Its source lives in a hidden home folder, the project archive, not in a git repository, and it has no public release. Treat it as an internal or portfolio case study, not as a downloadable product.

Biography

Terminal commands are powerful and unforgiving. Most people who use a Mac's command line know what they want — "find the big files in Downloads", "what's using port 8080", "keep the Mac awake for an hour" — but not the exact flags, especially since macOS ships BSD tools that differ quietly from the Linux versions most online answers assume. Cloud chatbots can help, but they mean pasting your folder names and system details into a remote service, and copying commands back by hand.

mlx-cli started from a direct request: let the owner type a request in human terms and have his most capable offline MLX model put the right zsh command on the line. The design sticks to a few principles: the model runs locally, the user keeps the final say, and quality is measured rather than assumed.

How it feels to use. In zsh, you type mlx-cli show the top running processes. A moment later top -o cpu sits on your next prompt line, already typed but not executed. You can edit it, press Enter, or discard it. The same works without the prefix: type English straight onto the prompt and press Ctrl-G, and the line is replaced in place. If a command fails, mlx-fix (optionally followed by what went wrong) rewrites your previous command. In testing it turned sed -i 's/foo/bar/' notes.txt into the macOS-correct sed -i '' …, and date -d yesterday into date -v -1d. mlx-cli --explain "<command>" describes any command part by part, ending with a "Risk:" line.

Safety without nagging. Nothing runs on its own. Every suggestion passes through a pattern check that flags deleting (any rm, find -delete), killing processes, sudo, disk operations, piping downloads into a shell, destructive git/Docker/Homebrew actions and changes to Mac settings (pmset, defaults write). In zsh that shows a red warning. In bash, the standalone version asks before running and defaults to "No" for risky commands. The model is also told to do only what was asked. That rule came from testing, where one model "helpfully" added && rm -rf Projects after creating a zip.

Choosing the model on evidence. A distinctive part of the project is its built-in benchmark. mlx-cli --compare <model> runs 31 everyday requests through two models, marks each answer ✓ or ✗, and reports speed. An answer passes only if the command is correct, adds nothing risky that wasn't asked for, and doesn't loop. On 2026-10-04 the results were Qwen3-14B 28/31, Ministral-3 14B 27/31 and Qwen3-Coder-30B 24/31. The coding specialist was fastest but padded commands and sometimes repeated itself until cut off, so the general model was kept. When a new candidate finishes downloading, a watcher scores it automatically and switches only if it scores at least as well. It did this twice: it kept Qwen3-14B over Qwen3-Coder-30B (28 vs 26) and over a pruned Qwen3-Coder-Next "REAP" 40B (29 vs 26, on 2026-10-05).

Loops, measured honestly. Testing showed that Qwen3 models with greedy decoding can loop (grep -v x | grep -v x | …). A repetition penalty was tried and measurably made results worse, so it was turned off. Instead mlx-cli detects a looping answer, never hands it over, and retries up to twice using Qwen's recommended sampling settings. If all three attempts loop, it asks you to rephrase.

A personal offline model library. Alongside the tool, a resumable download queue built a 21-model library (~211 GB) on an external drive. It covers general reasoning, coding, medical/neuroscience text, vision, OCR, speech-to-text and document search, all chosen to fit a 36 GB Mac. A watchdog restarted stalled downloads after drive disconnects and sleep. The queue log shows the whole set finished on 2026-10-05. mlx-cli --models, --use, --chat and --downloads manage that library from the terminal.

What it isn't. It isn't packaged, published or cross-platform. It was built and verified on one Mac, and its paths assume that Mac's layout (an external drive named TOSHIBA). It's a working personal tool and a well-documented case study in using local AI models responsibly: a human-in-the-loop design, explicit risk flagging, and choosing a model by benchmark rather than by name.

Features (authored vs dependencies)

Dependencies (not authored): Apple MLX and mlx-lm 0.32.0 (mlx_lm.server and mlx_lm.chat), transformers 5.18, huggingface_hub's hf CLI, and the third-party model weights (Qwen, Mistral, Google Gemma/MedGemma, DeepSeek, OpenAI gpt-oss, GLM, Whisper, Parakeet, and others), each under its own licence.

What a visitor could see: terminal sessions only. There is no graphical interface.

Technical foundations

• Core: a single Python file (mlx_cli.py). It builds a system prompt (macOS version, BSD rules, few-shot examples, folder context), queries a local OpenAI-compatible mlx_lm.server if one is running, otherwise loads the model in-process, then cleans the output (strips thinking tags, gpt-oss channels and code fences) and checks it.
• Shell integration: mlx-cli.zsh (function, ZLE widget, mlx-fix, completion, autostart), sourced from the project archive. bin/mlx-cli is the bash/standalone version, linked from the project archive.
• Config: the project archive sets the model path, port 18765 (8765 was taken by the studio’s Global Memory server), the 160-token limit and the repetition penalty (1.0, off).
• Library tooling: the project archive downloads models in order with .complete markers and retries. download-watchdog.sh restarts a downloader that's been stalled for 5 minutes and a queue that has stopped.
• macOS specifics: large models needed the GPU wired-memory cap reset (iogpu.wired_limit_mb), because it had been set to 4096 on that Mac. LaunchAgents were tried for autostart and rejected, because macOS blocks them from reading external drives. The helpers start from the shell instead.

Maturity (all evidence 2026-10-04/05, one Mac)

There are no versions, no git history, no CI and no packaging. Its state after 2026-10-05 is unknown; nothing was re-run for this profile.

Limitations, roadmap, FAQs

Limitations:

• Built for one Mac: hard-coded the project archive paths, macOS on Apple Silicon only.
• The model can be wrong. Every model failed "keep the Mac awake for an hour", reaching for pmset instead of caffeinate, and suggestions sometimes over-filter output.
• The risk check is pattern-based, so it isn't a guarantee.
• The background server holds about 9 GB of memory.
• Without the server, each request takes about 15 s.
• No unit-test suite beyond the benchmark, no packaging, no git.
• The library's reasoning, medical, vision and speech models were downloaded but have not been evaluated or integrated, apart from a one-question --chat smoke test with Qwen3-14B. Make no claims about them.

Roadmap (aspirational, nothing started):

• Packaging with configurable paths.
• A git repository.
• Capturing demo media.
• Optionally wiring the speech-to-text models in for voice requests. That's an idea only.

FAQs:

• Does anything leave my Mac? Generating commands needs no network. Only the one-off model downloads used the internet.
• Will it run commands by itself? No. In zsh it only places the command on your prompt; in bash it asks first.
• Which model does it use? Whichever scores best on its 31-request benchmark. On 2026-10-04/05 that was Qwen3-14B (4-bit, about 8 GB).
• Why not the coding-specialist models? In testing they were faster but padded commands, made up dcache, and sometimes looped. They scored 24–26 against 28–29.
• What hardware does it need? An Apple Silicon Mac. The tested library models need roughly 8–24 GB of free memory.