KaozKit

KaozKit is an open-source Swift package by Sébastien Burel that embeds the Moddable XS JavaScript engine to run autonomous LLM agents inside native macOS apps. Agents are written as small JS modules, can call tools, read and write memory, and survive app restarts through full heap snapshots. The project is the foundation of TyKaoz, a forthcoming private AI wiki app for macOS built in Rennes, France.

What It Is

KaozKit sits at the intersection of Swift app development and LLM agent runtimes. Rather than running agents in Node.js or Python, it embeds the XS engine — originally built for embedded systems — directly in a Swift package. An agent is a JS module that exports a run(input) function; it drives a language model, calls registered tools, and persists state across process restarts via heap snapshots. The package targets macOS 26+ on Apple Silicon and requires Swift 6 and Xcode 26.

Architecture: Layered Swift Package

KaozKit is structured as a single SwiftPM package with distinct product layers:

• KaozJSCore (C) — the raw XS engine plus an async-settle bridge
• KaozJS — Swift wrapper: dedicated thread, CFRunLoop, snapshot, module roots
• KaozHostC (C) — XS host functions exposing host.llm, host.tool, host.memory, host.schedule
• KaozKit — full agent runtime: providers, tools, memory, channels, persona
• KaozMLX — optional on-device Apple Silicon inference via MLX (opt-in, heavy deps)
• kaoz — headless CLI and resident daemon

This layering means a project that only needs a JS↔Swift bridge can depend on KaozJS alone, while agent projects pull in KaozKit.

Why XS Instead of JavaScriptCore

The README explains the choice: JSC ships with the OS but lacks the capabilities KaozKit needs. XS adds heap snapshots (writeSnapshot() / init(snapshot:)) that serialize the entire JS heap so resident agents survive relaunches with full state intact. It also supports multi-machine services — agents can spawn sub-agents as isolated XS machines with alien-marshalled calls between them — and enforces confinement by construction, restricting module resolution to registered roots so secrets never enter JS. XS's embedded-systems heritage also means a tiny memory footprint, making one engine per agent a practical architecture.

Provider and Tool Ecosystem

KaozKit ships native Swift providers for Anthropic, Google Gemini, OpenAI, Ollama, LM Studio, DeepSeek, Mistral, Qwen, and Apple Intelligence (on-device Foundation Models), plus a ComfyUI provider for image generation. JS-defined providers cover the same major APIs over a native HTTP primitive. The optional KaozMLX module adds MLXLLMProvider and MLXEmbeddingProvider for fully on-device Apple Silicon inference with Hugging Face model management.

Tools are registered in a ToolRegistry and conform to a Tool protocol. Read tools (file access, directory listing, grep, web search via Brave, news search) are safe by default. Actuation tools — file writes, shell execution, HTTP requests, email send/read — are opt-in and confined to explicitly authorized roots or allow-lists. An HTTPPluginTool builds tools from a declarative JSON manifest, enabling any REST API without writing code.

CLI, Resident Mode, and Debugging

The kaoz CLI runs agents headlessly: kaoz <agent.js> [flags]. Resident mode (--resident) keeps one engine alive across many deliveries, with --state enabling heap snapshots across process restarts and --state-auto checkpointing after every delivery. --webhook PORT turns a resident agent into an inbound HTTP handler.

For debugging, KaozKit connects to the XS source-level debugger xsbug automatically — no flag required. Developers get breakpoints, stepping, call stacks, and variable inspection inside the agent's JavaScript, which the README notes is not available in Node or Python agent harnesses. A command-line variant, xsdb, can be driven by scripts or by an LLM like Claude Code.

Update: KaozKit 0.2.0

The latest release is v0.2.0, published on 2026-09-13. The repository was created in June 2026 and last pushed in September 2026, indicating active early development. The README describes the project as "young and moving fast," with the engine layer (KaozJS) covered by a regression suite and the agent runtime API still potentially evolving before 1.0. The project is MIT-licensed (original code), with the linked Moddable XS engine under GNU LGPL v3 supplied separately via a local Moddable checkout.