Getting Started — apfelclaw docs

Prerequisites

Before running apfelclaw, make sure you have the following installed:

macOS 13 or newer
Swift 6.3+
Bun 1.0+
apfel installed and available on your PATH (github.com/Arthur-Ficial/apfel)

apfelclaw depends on Apple platform APIs (EventKit, Apple Mail, Spotlight) and uses apfel for on-device model execution. It is macOS-only.

The repository is organized as a small monorepo:

Path	Description
`packages/apfelclaw-server`	Swift backend runtime — local API, tool execution, conversation management, and persistence
`apps/tui`	Terminal UI client built with OpenTUI and Bun
`./apfelclaw`	Convenience launcher script for the backend server

From the repository root:

./apfelclaw

The server starts listening on 127.0.0.1:4242. This launcher script builds and runs the Swift server package.

In a second terminal:

cd apps/tui
bun install

bun run dev

You should now see the terminal interface connected to your local backend.

You can also use the convenience scripts from the repo root:

./apfelclaw          # start backend server
npm run dev:server   # alternative server start
npm run dev:tui      # start TUI client

Config lives in ~/.apfelclaw/config.json and persists across server restarts. SQLite memory is stored at ~/.apfelclaw/memory.sqlite.

A typical config looks like:

{
  "assistantName": "Apfelclaw",
  "userName": "You",
  "approvalMode": "trusted-readonly",
  "debug": false
}

See the API Reference for details on reading and updating config via the REST API.

Remote control providers store their own state separately in ~/.apfelclaw/remote-control.json.