# KaozKit

> A Swift package that embeds the XS JavaScript engine to run autonomous LLM agents with heap snapshots, resident state, and confined tools on macOS Apple Silicon.

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.

## Features
- Autonomous LLM agents written in JavaScript running inside Swift apps
- XS engine heap snapshots for resident agent state across process restarts
- Multi-machine sub-agent spawning with isolated XS engines
- Confinement by construction: module resolution restricted to registered roots
- Native Swift providers: Anthropic, OpenAI, Google Gemini, Ollama, Apple Intelligence, ComfyUI
- Optional KaozMLX module for on-device Apple Silicon inference via MLX
- JS-defined providers over native HTTP primitive
- Tool registry with read tools (file, web search, news) and opt-in actuation tools (file write, shell, HTTP, email)
- HTTPPluginTool: build tools from declarative JSON manifests for any REST API
- SemanticMemoryStore with embedding-ranked recall
- kaoz headless CLI for running agents standalone
- Resident mode with per-delivery heap snapshots and webhook inbound HTTP
- Source-level JavaScript debugging via xsbug and xsdb
- Self-scheduling agents with host.schedule and host.every
- Streaming LLM responses with onToken callback
- Email send/read via SMTP/IMAP with recipient confinement
- SwiftPM layered package: KaozJS, KaozKit, KaozMLX as separate products

## Integrations
Anthropic Claude, OpenAI GPT, Google Gemini, Ollama, Apple Intelligence (Foundation Models), MLX (Apple Silicon on-device inference), ComfyUI (image generation), LM Studio, DeepSeek, Mistral, Qwen, Brave Search API, NewsAPI, Hugging Face (model management via KaozMLX), Proton Bridge (email), SMTP/IMAP servers, Moddable XS engine

## Platforms
MACOS, IOS, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.2.0

## Links
- Website: https://www.tykaoz.bzh/en/
- Documentation: https://github.com/sebastien-burel/KaozKit/blob/main/CLAUDE.md
- Repository: https://github.com/sebastien-burel/KaozKit
- EveryDev.ai: https://www.everydev.ai/tools/kaozkit