apfel-gui

Native macOS debug GUI for apfel.

brew install Arthur-Ficial/tap/apfel-gui

apfel-gui

That's it. apfel installs automatically as a dependency.

Requires macOS 26+ (Tahoe) on Apple Silicon with Apple Intelligence enabled.

What it does

A SwiftUI desktop app that talks to apfel --serve via HTTP. Pro debugging tool that shows everything: raw HTTP requests/responses, full MCP JSON-RPC protocol data, server-side event traces, token budgets, SSE streams. Nothing hidden, nothing dumbed down.

On launch, apfel-gui starts apfel --serve in the background with MCP tool servers, waits for the health check, and opens the debug window. Quitting the app stops the server.

Debug Inspector

The debug inspector shows the full timeline of every request, in order:

MCP Tool Debugging

MCP servers are auto-discovered and loaded on startup. apfel handles all MCP logic: tool discovery, injection, call detection, execution, and re-prompting. The GUI shows the full raw protocol data.

Bundled servers:

• debug-tools - debug_echo, timestamp, system_info
• calculator (from apfel repo, if found) - add, subtract, multiply, divide, sqrt, power, round_number

Example debug output for a tool call:

MCP Request (JSON-RPC tools/call)
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "multiply",
    "arguments": { "a": 247, "b": 83 }
  }
}

MCP Response (JSON-RPC result)
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "20501" }],
    "isError": false
  }
}

Custom MCP servers can be added via the MCP settings in the toolbar.

Features

• Chat with streaming responses
• Debug inspector with full request/response timeline
• MCP debugging with raw JSON-RPC for every tool call
• Server event trace showing context build, chunk deltas, tool execution
• Live request log with stats (uptime, req/min, errors, tokens)
• Model settings for temperature, max tokens, seed, JSON mode
• Context strategies - newest-first, oldest-first, sliding-window, summarize, strict
• Typed errors with content policy, context overflow, rate limit handling
• Speech-to-text and text-to-speech (on-device)
• Self-discussion mode for AI self-debate
• Any OpenAI-compatible server via advanced connection settings

Keyboard Shortcuts

Troubleshooting MCP servers

A malformed user-configured MCP path can prevent apfel --serve from becoming ready, which leaves the GUI window unable to load. Since the Settings panel lives behind the GUI, you cannot edit the path from there when the app fails to start.

Two CLI escape hatches handle this without touching the plist by hand:

apfel-gui --list-mcp-servers       # show the configured paths
apfel-gui --reset-mcp-servers      # clear all user MCP paths, then relaunch
apfel-gui --safe-mode              # one-shot launch that ignores user paths

If you prefer raw defaults, the same key:

defaults read com.arthurficial.apfel-gui mcpServerPaths
defaults delete com.arthurficial.apfel-gui mcpServerPaths

Build from source

git clone https://github.com/Arthur-Ficial/apfel-gui.git
cd apfel-gui
make install

Requires apfel installed and in PATH.

API

Uses the OpenAI-compatible API from apfel --serve on port 11438:

AI Control Mode

Start with --api to enable full programmatic control via HTTP on port 11439:

apfel-gui --api

Every GUI action is controllable. No clicking needed.

# Send a message and get the response
curl localhost:11439/send -d '{"message": "What is 99 times 42?"}'

# Change settings
curl localhost:11439/settings -d '{"temperature": 0.7, "voice_id": "com.apple.voice.premium.en-US.Ava"}'

# Get full debug info for a message
curl localhost:11439/inspect -d '{"index": -1}'

# List all installed voices
curl localhost:11439/voices

# Speak text with a specific voice
curl localhost:11439/speak -d '{"text": "Hello", "voice_id": "com.apple.voice.premium.en-US.Ava"}'

All endpoints:

Related

• apfel - Apple Intelligence from the command line