Imported from lohbe/lfb (AGENTS.md). Install upstream with npx skills add lohbe/lfb. Copyright stays with the author.

AGENTS.md

Guidance for AI coding agents working in this repository.

What this repo is

A build-automation repo (no application code) that produces a single self-contained llamafile executable bundling the Gemma 4 E4B (it, QAT, Q4_0) GGUF model into the llamafile launcher, installed at ~/.local/bin/gemma-4-E4B-it-qat-q4_0.llamafile.

The entire build is driven by justfile. There is no src/, no package manager, no CI. The only deliverables are justfile, this file, and README.md.

Layout

lfb/
├── justfile        # all build logic — the only "code" in this repo
├── README.md       # human docs
├── AGENTS.md       # this file
├── .gitignore
├── cache/          # (generated) downloaded model + llamafile binary — ~5.5 GB
├── build/          # (generated) .args and the packed <name>.llamafile — ~6.2 GB
└── vendor/zipalign # (generated) shallow clone of jart/zipalign + its `zipalign` binary

cache/, build/, vendor/ are always regenerable; never hand-edit or commit them.

Upstream facts (verified 2026-09)

llamafile also ships a llamafile-0.10.5-thin (42 MB) asset; we deliberately use the full universal binary because the embedded TUI/Web-UI assets are needed. Do not "upgrade" to -thin without verifying the UI still works.

justfile contract

• All config lives in the variable block at the top; every variable is CLI-overridable (just all include_mmproj=1). Keep new config there, not inlined in recipes.
• all (default) = package + verify; build is an alias of package.
• clean must remove exactly cache/, build/, vendor/. uninstall removes only the installed binary. Don't merge them.

Non-negotiable build constraints (why the recipe looks the way it does)

1. .llamafile is a ZIP (APE) whose first asset is the launcher. We therefore cp cache/llamafile <name>.llamafile and append the other assets — never zip from scratch.
2. zipalign is append-only and never reflows. Each invocation leaves the old central directory as junk. Always start from a fresh launcher copy and pass all files in a single zipalign -j0 invocation (binary, model [, mmproj], .args). Never call zipalign twice on the same target.
3. -j0 is required for the model: store (uncompressed) + strip path components. Compressed weights cannot be mmap()ed by the launcher. Asset names in the archive are the basenames (e.g. gemma-4-E4B_q4_0-it.gguf, .args), which is why .args references /zip/gemma-4-E4B_q4_0-it.gguf with the /zip/ prefix.
4. .args format: one argument per line; the final line must be the literal token ... (replaced at runtime by user-supplied CLI args). -m <model> is the only required arg.
5. Downloads are idempotent: a non-empty cached file skips re-download (test -s), and curl -C - resumes partial files. Preserve this when editing cache-* tasks.
6. macOS Gatekeeper: keep the xattr -d com.apple.quarantine step (guarded, best-effort) after install, or the installed binary won't launch on a fresh copy.

Conventions

• Shell in recipes is POSIX sh -eu (just default); no bashisms.
• Every step prints a ✓ / ↓ status line; keep output greppable and quiet.
• Pinned versions (llamafile_version) are intentional for reproducibility — bump them deliberately, with a note in README.md Provenance.
• Do not add runtime behavior to the model (system prompts etc.) unless asked; .args stays minimal (-m, optional --mmproj, --no-mmap, ...).

Common commands

just --list                  # task overview
just all                     # full build + verify
just all include_mmproj=1    # multimodal bundle (+~1 GB)
just verify                  # check archive entries + installed binary
just clean && just all       # from-scratch rebuild
just uninstall               # remove installed binary only