The macOS App

Haptix for Mac is a menu bar application that provides the UI for the Haptix daemon and manages connections to your iOS devices.

Overview

When you launch Haptix, it sits in your menu bar. The Haptix daemon (haptix-server) runs as a launchd service, starts the MCP server on localhost:4278, discovers USB-connected devices, and handles the full connection lifecycle — authentication, command relay, and reconnection. The menu bar app provides the visual interface.

What it does

Runs the MCP server — The daemon listens on localhost:4278/mcp for connections from AI agents (Streamable HTTP)
Discovers devices — Detects iOS apps running HaptixKit on USB-connected devices
Relays commands — Routes MCP tool calls from the agent to the device over WebSocket
Captures the screen — Server-side CoreMediaIO screen capture for compositor screenshots and session recording
Manages sessions — Tracks session lifecycle, tool call counts, and recording

Click the Haptix icon in the menu bar to see:

Connected devices — Which devices are currently connected and their status
Session info — Active session details (if an agent session is running)
Settings — Open the settings window
Quit — Stop the MCP server and exit

Settings

The settings window is where you configure your license and server preferences.

License key

Enter your Haptix license key (HPTX-XXXX-XXXX-XXXX). The app validates it against the key in your iOS app's Haptix.start(license:) call. Both must match for commands to work.

Command Line Tool

Install the haptix CLI to /usr/local/bin/haptix. This gives you terminal access to all MCP tools and server management commands. See the CLI Reference for details.

Server

The MCP server runs on localhost:4278 by default. This port is fixed and cannot be changed. The server uses Streamable HTTP for the MCP transport.

Connection lifecycle

Discovery

When your iOS app calls Haptix.start(license:), the SDK starts a WebSocket server on fixed port 4279. The daemon detects USB-connected devices automatically via devicectl — no IP addresses, no network configuration.

Connection

The AI agent calls start_session, which auto-discovers the USB device
The daemon authenticates with the SDK using a license key handshake
The connection is established and the agent can issue commands

USB connections are secure by nature — plugging in the cable is the trust handshake.

Reconnection

If the app is restarted (e.g., after a rebuild in Xcode), the SDK re-advertises and the daemon reconnects automatically. The agent just needs a new start_session.

Multi-device

The daemon can discover and track multiple USB devices simultaneously. Use the list_devices tool to see all available devices and select_device to bind the session to a specific one.

Activity indicator

When an AI agent is actively working, a blue gradient border (the "activity halo") appears around the edge of the device screen. This gives you a visual indicator that the agent is interacting with your app.

The halo activates automatically when the agent calls any tool
It deactivates automatically after ~10 seconds of inactivity
During an active session (start_session → end_session), the halo stays on

Tap indicator

When the agent performs a tap, a small visual indicator appears on the device screen at the tap location. This helps you see exactly where the agent is interacting.

Console capture

The daemon captures console output from your iOS app (print statements, NSLog, os_log, errors) and makes it available to the agent. This output is:

Automatically included in every gesture response
Available on demand via the get_console_output tool
Filterable by level (debug, info, error, fault), source (stdout, stderr, os_log), and text search

Session recording

When an agent calls start_session, the daemon begins recording the session — screen capture video and tool call logs. When the agent calls end_session, recording stops and a summary is returned with duration and tool call counts.

Screenshots of the macOS app interface will be added here soon.