Cadabra.app

Cadabra.app - macOS applet to run large language models locally, to chat with coding agents that speak ACP (Agent Client Protocol), and to keep either one's work in an AgentVM box, a virtual machine on your Mac

What Cadabra does

• Local models. Runs MLX and GGUF models on your Mac, with a native chat and tools the model can call (files and shell, web search, PDF, time).
• ACP agents. Drives external agents such as Claude Code, Codex, OpenCode or Gemini from the same chat window: any local agent that speaks ACP.
• AgentVM boxes. An agent can run in a separate macOS or Linux in a virtual machine instead of on your Mac, with one project folder shared, and so can a local model's tools (in a macOS box). Needs macOS 27 and the AgentVM app: https://github.com/abra-code/AgentVMApp
• Review and undo. A snapshot of the project before a session lets you see what the session changed and put any of it back.

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

App	Version	Chat UI	Engines
Cadabra.app	2.1.1	native (ActionUI Chat)	MLX (mlx-agent) + GGUF (llama-server), or an external ACP agent
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 local LLMs. An external agent uses whatever service it is set up for.

---

Cadabra.app (2.1.1)

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

External ACP agents

ACP (Agent Client Protocol) is the protocol a chat application and an agent talk over. Cadabra's own chat with a local model uses it, and so can any agent installed on your Mac that speaks it.

• Select ACP Agent keeps the agents by name. A catalog comes with Cadabra: Claude Code and Codex (through their ACP adapters), OpenCode, Gemini, GitHub Copilot, Cursor, Grok, Kilo, Kimi Code, Mistral Vibe and Qwen Code. Any other agent is added by its command.
• Cadabra does not install the agents. Test says whether an agent is on this Mac and answers.
• For each agent you choose how much of Cadabra's MCP tooling it gets: nothing, the read-only servers, or all of them.
• Runs in chooses where the agent works: this Mac, or an AgentVM box.

AgentVM boxes (macOS 27 or later)

An agent that can run commands can do anything your account can. An AgentVM box is a separate macOS or Linux running in a virtual machine on your Mac. What happens there stays there, apart from the one project folder you share with it.

• An external agent in a box. The agent and every tool it starts run inside the box: a kept box, or a new disposable one that is deleted when the chat window closes.
• A local model's tools in a box. The model stays on your Mac, since it needs the Mac's memory and graphics processor; every tool call it makes runs in a macOS box.
• Network. A box reaches only the hosts its rules allow. A window lists the hosts it reached and those it was refused, and a refused host can be allowed there.
• Keys. An agent in a box cannot read the keys on your Mac. Keys... stores an API key in your login Keychain and gives the agent the one key you choose.
• Review and undo. Cadabra snapshots the project before a session (on by default for a box). Review Changes lists what the session changed, shows each file's differences, and undoes one change or all of them. Changes that could run something on your Mac later, such as a git hook, are flagged and listed first.
• Tools > AgentVM Boxes lists the boxes and starts and stops them.
• Linux boxes run external agents with the agents' own tools. Cadabra's MCP servers are macOS programs and run in macOS boxes only.

Images and boxes are made in the AgentVM app, a separate application:
https://github.com/abra-code/AgentVMApp/releases
On a macOS older than 27 everything runs on your Mac, as before. Help > AgentVM Boxes Help in the app explains all of it.

Sandbox on your Mac

• The Local server (files and shell) runs in a sandbox that allows the project and a list of folders. Sandbox packs are named sets of folders for one kind of work (Xcode and Swift, CMake, Node.js, Python, Homebrew and others); you can record one of your own from a command.
• Allow a Folder... and Allow Packs... in a chat window let the tools use more while a conversation is running.
• The engines can run in a sandbox too: llama-server with Run Engine in Sandbox on, and mlx-agent when no tools run on your Mac.

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 make
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. 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)