Experimental

apfelclaw

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

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.

⚙️

apfelclaw-server

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

packages/apfelclaw-server
🖥️

TUI client

Terminal user interface built with OpenTUI and Bun, connecting to the local API.

apps/tui
✈️

Telegram connection

Optional remote access through a private Telegram bot, linked from the TUI and handled by the local backend.

/remotecontrol setup telegram
🚀

Launcher

A convenience shell script at the repo root that starts the backend server in one command.

./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.

Prerequisites

Quick start

1

Start the backend server

./apfelclaw

The server listens on 127.0.0.1:4242.

2

Install TUI dependencies

cd apps/tui
bun install
3

Start the TUI client

bun run dev

Or use the root convenience scripts: 

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

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-server/0.1.0

Configuration

Config lives in ~/.apfelclaw/config.json and persists across server restarts. 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.