Experimental

apfelclaw

A locally running AI agent for macOS tasks, powered by Apple's Foundation model via apfel. 

brew tap julianYaman/apfelclaw
brew install apfelclaw
View on GitHub Docs Get started
License Stars Last commit Open issues
Early development — This project is an experiment exploring how well Apple's Foundation model works as an agent. It is not meant for production use or real-world tasks yet. Use at your own risk — we cannot guarantee its reliability or security.

Project structure

The repository is organized as a small monorepo with a Swift backend and a terminal UI client, with optional Telegram remote control backed by the same local runtime.

⚙️

Swift backend

Swift backend runtime — local API, tool execution, conversation management, and persistence.

packages/apfelclaw-server
🖥️

Chat app

Separate terminal chat application built with OpenTUI and Bun, connecting to the local API.

apps/tui
✈️

Telegram connection

Optional remote access through a private Telegram bot, linked during onboarding or later from chat, and handled by the local backend.

/remotecontrol setup telegram
🚀

Command tool

The Node-based apfelclaw CLI owns onboarding, service lifecycle, status, updates, and chat launch.

apfelclaw

Status

Currently macOS-only. The backend depends on Apple platform APIs like EventKit, Apple Mail, and Spotlight-backed file search, and expects apfel to be installed locally for model execution. Homebrew installs also pull in the Node runtime for the command tool.

Prerequisites

Quick start

1

Install with Homebrew

brew tap julianYaman/apfelclaw
brew install apfelclaw

This installs the command tool, chat app, and backend runtime.

2

Run onboarding

apfelclaw
# complete onboarding

The onboarding guide saves your defaults, starts the backend, and can optionally set up Telegram.

3

Launch chat

apfelclaw chat

Or use the root convenience scripts: 

apfelclaw setup       # rerun onboarding
apfelclaw serve       # foreground backend
apfelclaw chat        # launch chat app
apfelclaw --status    # rich local status

Need a prompt to start with? Try Starter Prompts.

API endpoints

The backend exposes a local REST API with WebSocket support for live session events.

Method Endpoint
GET/health
GET/config
PATCH/config
GET/tools
GET/sessions
POST/sessions
GET /sessions/:id/messages
POST /sessions/:id/messages
WS /sessions/:id/stream

Response header: Server: apfelclaw/0.2.0

Configuration

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

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

Supported approvalMode values: always, ask-once-per-tool-per-session, trusted-readonly.

Contributing

Contribution guidelines live in CONTRIBUTING.md. Please read that file before opening a pull request.