Cadabra.app

Cadabra.app - macOS applet to run large language models locally

This repo holds two applets that share a lineage and a codebase, but not a UI:

App	Version	Chat UI	Engines
Cadabra.app	2.0	native (ActionUI Chat)	MLX (mlx-agent) + GGUF (llama-server)
AIChat.app	1.2	llama.cpp WebUI in a WebKit view	GGUF (llama-server)

Cadabra.app is the current app. AIChat.app 1.2 is kept as the previous generation and still works, but the new work happens in Cadabra.

Both apps are self-contained with the exception of external model files, which can be downloaded from within the app or manually from:
https://huggingface.co/models
or
https://www.modelscope.cn/models

After the initial setup no network is required to query the LLMs.

---

Cadabra.app (2.0)

One etymology of abra-cadabra is "I create as I speak" - the speaking carries over from the old name.

The chat is native: an ActionUI Chat element talking to the model over ACP, not a web view. There is no bundled WebUI.

Two engines, picked from the model itself:

• MLX - an Apple-silicon model directory holding config.json + *.safetensors shards, run by the embedded mlx-agent (MLX / Metal, arm64 only):
  https://github.com/abra-code/mlx-agent
• GGUF - a single .gguf file, run by llama-server from the llama.cpp project:
  https://github.com/ggml-org/llama.cpp/

Selecting a model is enough - a file is treated as GGUF, a directory with safetensors shards as MLX - so both formats sit side by side in the same model list.

Features

• Local Models browser with a model selector, RAM-fit advisory, and per-model benchmark
• Hugging Face browser for searching, filtering (Any / MLX / GGUF), downloading, and starting models
• Chat history: named, persisted conversations you can rename, reveal, delete, and continue
• In-place model switching from the chat toolbar, without opening a second window
• MCP tool support over stdio, owned by mlx-agent, with a servers dialog and an inspector:
  • Time (embedded time-mcp, a native program, no network)
  • Web Search & Fetch (duckduckgo-mcp-server)
  • PDF (embedded pdfutil, no network): inspection always, plus optional editing - merge, page ops, metadata, form fill, watermark, shrink - whose outputs are always new files (never an overwrite) and are permission-gated per call
  • Local files & shell, sandboxed via replay, with explicit read-only and read-write path lists
  • a session-wide Allow Network master switch that hard-gates the networked servers

Preferences and state live under ~/Library/Application Support/Cadabra and the com.abracode.Cadabra preference domains.

---

AIChat.app (1.2)

The original app: open a local GGUF file and start a chat in a WebKit view. Version 1.1 added a Local Models browser with a model selector dialog, and a Hugging Face browser for browsing, downloading, and starting models directly from the app.

It uses llama-server from the llama.cpp project:
https://github.com/ggml-org/llama.cpp/

llama-server comes with its own complete WebUI. The Contents/Resources/WebUI dir contains a slight modification of this UI to display the AIChat.png image at the landing page. llama-server is started locally from the app bundle with the following:

	webui_dir_path="$OMC_APP_BUNDLE_PATH/Contents/Resources/WebUI"
	"$OMC_APP_BUNDLE_PATH/Contents/Support/Llama.cpp/llama-server" --host 127.0.0.1 --port $port_num --path "$webui_dir_path" --model "$AICHAT_MODEL_PATH" &

You can place a chosen GGUF file in the applet's Contents/Resources and set AICHAT_MODEL_PATH in aichat.library.sh to make the applet with one model completely self-contained. Then, of course, you need to codesign the modified app.

MCP servers in 1.2 are reached through an HTTP mcp-proxy bridge, which is why the V1 bundle keeps its own Python packages copy. Cadabra dropped the proxy - it speaks stdio directly.

---

Populating and Updating the App Bundles

The instructions below are needed only if you are cloning the repo and not running a pre-built notarized app from a distribution archive.

Both app bundles require binaries that are excluded from git.

Cadabra.app engines (update-cadabra.sh)

update-cadabra.sh installs the runtime engines and tools into Cadabra.app, then codesigns the bundle and verifies that they actually launch (--help lists every option):

./update-cadabra.sh                              # everything: llama.cpp (latest release) and the rest built from source
./update-cadabra.sh --version=b8797              # pin the llama.cpp build tag
./update-cadabra.sh --skip-llama                 # rebuild and redeploy everything but llama.cpp

Component	Destination	Source
llama-server + dylibs	Contents/Support/Llama.cpp/	downloaded GitHub release
mlx-agent + resource bundles	Contents/Support/MLX/	built from source with xcodebuild
pdfutil	Contents/Support/	built from source with ./build.sh
replay	Contents/Support/	built from source with xcodebuild
time-mcp	Contents/Support/	built from source with cmake
Python MCP server (search)	Contents/Library/Packages/	pip install with the bundle's own python3

mlx-agent, pdfutil, replay and time-mcp are built from sibling checkouts (--agent-repo=, --pdfutil-repo=, --replay-repo=, --time-repo=), each as it is. A tool with no checkout is built from the source of its newest version tag, which the script downloads from GitHub. time-mcp needs cmake. No WebUI is downloaded or patched - Cadabra's chat is native.

Cadabra carries no agent-vm and does not install one. Boxes need macOS 27 or later and run the agent-vm that the AgentVM app (https://github.com/abra-code/AgentVMApp) installs for the user (~/.local/bin/agent-vm), the same one Terminal runs. The AgentVM app also makes the images and boxes; Cadabra's Tools > AgentVM Boxes only shows the boxes and starts and stops them. The developer setting /developer/agent-vm in Cadabra's settings file points it at another build, such as ~/Development/agent-vm/.build/signed/release/agent-vm. An earlier build's Contents/Support/AgentVM/ is removed by the script.

arm64 only: Cadabra runs only on Macs with Apple silicon, so every engine is built and deployed for arm64 alone, and the script refuses to run on an Intel Mac.

AIChat.app llama.cpp distribution (update-llama-cpp.sh)

update-llama-cpp.sh serves the V1 app (and Enoch), which renders its UI from llama.cpp's WebUI and therefore downloads and patches index.html / bundle.js / bundle.css on every update:

./update-llama-cpp.sh                                # auto-detect latest version and host architecture
./update-llama-cpp.sh --version=b8797                # install specific version
./update-llama-cpp.sh --version=b8797 --arch=arm64   # specify both version and architecture
./update-llama-cpp.sh --app=/path/to/Enoch.app       # name the target bundle explicitly

The script will:

• Download the llama.cpp release from https://github.com/ggml-org/llama.cpp/releases
• Extract and install the llama-server binary and all required dylibs to AIChat.app/Contents/Support/Llama.cpp/
• Update the WebUI (index.html, bundle.js, bundle.css) with AIChat customizations

The target bundle is AIChat.app when it exists beside the script, otherwise the sole *.app there (single-app repos such as Enoch); --app=PATH names one explicitly, and two candidates with no AIChat.app is an error rather than a guess. Cadabra.app is refused outright - use update-cadabra.sh for it.

Framework and executable (AppletBuilder.app)

Use OMC's AppletBuilder.app to add the framework and executable binary to either bundle:

• Abracode.framework -> <App>.app/Contents/Frameworks/
• Cadabra -> Cadabra.app/Contents/MacOS/
• AIChat -> AIChat.app/Contents/MacOS/

These are managed separately from the engine distributions and should be added via AppletBuilder.app's workflow.

Binaries excluded from git

Cadabra.app - only the sources under Contents/Resources plus Info.plist/PkgInfo are tracked. Excluded:

Cadabra.app/Contents/Frameworks     Abracode.framework
Cadabra.app/Contents/MacOS          Cadabra
Cadabra.app/Contents/Library        embedded Python + MCP packages
Cadabra.app/Contents/Support        llama-server + dylibs, mlx-agent, pdfutil, replay, time-mcp
Cadabra.app/Contents/_CodeSignature

AIChat.app excluded:

AIChat.app/Contents/MacOS               AIChat
AIChat.app/Contents/Frameworks          Abracode.framework
AIChat.app/Contents/Support/Llama.cpp   llama-server, *.dylib
AIChat.app/Contents/Support/replay
AIChat.app/Contents/Library/Python
AIChat.app/Contents/Library/Packages
AIChat.app/Contents/Resources/WebUI     bundle.js, bundle.css
AIChat.app/Contents/_CodeSignature

Sources: https://github.com/abra-code/OMC/releases (OMCApplet, Abracode.framework, replay) https://github.com/ggml-org/llama.cpp/releases (llama-server, dylibs) https://github.com/abra-code/mlx-agent (mlx-agent) https://github.com/abra-code/pdfutil (pdfutil) https://github.com/abra-code/time-mcp (time-mcp)