// Build AFM from scratch — submodules, patches, webui, and Swift build. Use when user types /build-afm, asks to build afm, or needs a fresh build from a clean clone.
Use when promoting afm to a stable release — builds from main HEAD or a nightly commit, verifies patches, updates Homebrew stable tap (afm.rb), builds a PyPI wheel, updates README and version files, and verifies both brew install and pip install work. Repo admin only.
Use when user wants to build a PyPI wheel from an existing compiled afm binary and publish to PyPI. Covers staging assets, building the wheel, and providing the uv publish command. Only for official stable releases, not nightly builds.
Build, test, and publish an afm-next nightly release — full from-scratch build, user testing pause, GitHub release, and Homebrew tap update. Use when user types /build-afm-nightly-publish or asks to publish a nightly build.
Test a pre-built afm binary at any path — runs pre-flight safety checks, then any combination of unit tests, assertions, smart analysis, promptfoo evals, batch validation, OpenAI compat, GPU profiling. Use when user wants to validate a binary post-build, after code changes, or before release.
Run and review the Promptfoo-based AFM agentic evaluation suite. Use when the user wants structured-output, tool-calling, grammar, guided-json, streaming, concurrency, or agentic QA coverage for AFM, and especially when they want help choosing harness options or interpreting failures.
Run the maclocal-api (AFM/MLX) test suite — automated assertions and smart analysis. Use when asked to test, validate, regression-check, or benchmark AFM before release, after code changes, or for model onboarding.
| name | build-afm |
| description | Build AFM from scratch — submodules, patches, webui, and Swift build. Use when user types /build-afm, asks to build afm, or needs a fresh build from a clean clone. |
| user_invocable | true |
Build the afm binary from scratch, suitable for a fresh clone or a full rebuild.
/build-afm — release build (default)/build-afm debug — debug build/build-afm release — explicit release buildBefore building, check that all required tools and environment are present. Run these checks and collect results:
# 1. Apple Silicon check (MLX requires arm64)
uname -m # must be "arm64"
# 2. macOS version (Package.swift requires macOS 26+)
sw_vers -productVersion # must be 26.0 or higher
# 3. Homebrew (must come before brew-installed tools)
brew --version
# 4. Xcode (full install — mlx-swift uses Metal framework SDK, not available in standalone CLI Tools)
xcode-select -p # must point to Xcode.app, NOT /Library/Developer/CommandLineTools
swift --version # needs Swift 5.9+ (swift-tools-version: 5.9)
# 5. Git (for submodule operations — installed via brew or Xcode)
git --version
# 6. Node.js + npm (for llama.cpp webui build — Svelte/Vite frontend)
node --version # Node 18+ recommended
npm --version
Present results as a checklist to the user in dependency order (install top-to-bottom). For each item, show pass/fail, reason, and install command (even on pass, for copy-paste on other machines):
| # | Prerequisite | Check | Status | Reason | Install |
|---|---|---|---|---|---|
| 1 | Apple Silicon | uname -m = arm64 | pass/fail | MLX framework requires ARM64 GPU | N/A (hardware requirement) |
| 2 | macOS 26+ (Tahoe) | sw_vers >= 26.0 | pass/fail | Foundation Models backend + SDK APIs | System Settings > Software Update |
| 3 | Homebrew | brew --version | pass/fail | Package manager — Git, Node.js depend on it | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
| 4 | Xcode (full) | xcode-select -p points to Xcode.app | pass/fail | mlx-swift uses Metal SDK (not in standalone CLI Tools) | Install from App Store → search "Xcode" |
| 5 | Swift 5.9+ | swift --version | pass/fail | swift-tools-version: 5.9 in Package.swift | Included with Xcode |
| 6 | Git | git --version | pass/fail | Submodule init (mlx-swift-lm, llama.cpp) | brew install git |
| 7 | Node.js 18+ | node --version | pass/fail | llama.cpp webui build (Svelte/Vite) | brew install node |
| 8 | npm | npm --version | pass/fail | npm install + npm run build for webui | Included with Node.js |
Important Xcode notes:
xcode-select --install) are NOT sufficient — mlx-swift imports the Metal framework which requires the full Xcode SDKxcode-select -p returns /Library/Developer/CommandLineTools, switch to Xcode: sudo xcode-select -s /Applications/Xcode.app/Contents/Developersudo xcodebuild -license acceptIf anything is missing, present the failing items with install commands and ask the user to confirm when ready. Alternative Node.js install:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && nvm install 22Do NOT proceed with the build until all prerequisites pass.
Parse the argument: if the user passes debug, use --debug. Otherwise default to release.
Run the full build script with NO skip flags:
./Scripts/build-from-scratch.sh # release (default)
./Scripts/build-from-scratch.sh --debug # debug
IMPORTANT: Never add --skip-submodules, --skip-patches, or --skip-webui. The point of this skill is a complete from-scratch build.
The script already handles:
git submodule update --init --recursiveScripts/apply-mlx-patches.sh (apply + verify)BuildInfo.swift (then restores it after build)__TEXT,__info_plist section is missing or doesn't contain NSSpeechRecognitionUsageDescription. Required by Sources/MacLocalAPI/Info.plist + Package.swift linker flags (-Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker …). Without this, macOS 26 SIGABRTs any Speech Recognition / microphone / camera call.After the build succeeds, report to the user:
afm binary (from the script output)<binary-path>/afm --versionDo NOT add example run commands, CLI options, or environment variables. Just report the binary path and version — the user knows how to run it.
If the build fails, show the error output and suggest checking:
xcode-select -p)