The Butler — Developers
How your Butler integrates with the core shell: navigation, routing, search, quick actions, alerts, tasks, calendar, and coordination APIs.
How The Butler fits in
The Butler is the host. Your custom Butler runs inside it—in a WebView, with no direct network or device access. The Butler provides the JS Bridge, navigation hooks, and container; you build the UI and logic and request data via the Data API.
Core Integration Points
The Butler provides multiple integration points for your Butler to extend platform functionality and provide seamless user experiences. Each integration point is documented in detail below with code examples and best practices.
1. Unified Navigation
Register your Butler with The Butler's unified navigation system so users can discover and access it from the core interface. Your Butler must provide metadata (name, description, icon) and handle deep links when users navigate to it. The Butler manages the navigation interface, badges, and routing between Butlers.
2. Global Search
Register your Butler as searchable so it appears in The Butler's global search results. When users issue commands or search queries, The Butler queries all installed Butlers to determine which ones are most likely to handle the request. Your Butler responds with likelihood scores and search results that help users find and access your Butler's functionality.
3. Coordination
The Butler acts as a coordination layer between all Butlers, managing routing, deep links, and context sharing. This enables Butlers to work together seamlessly—for example, an expense can link to a contact, a trip, and a receipt image. Your Butler can navigate to other Butlers, share context, and link entities across the platform.
4. Settings & Profile
The Butler centralizes account, preferences, data export, and Butler permissions in the core experience. Your Butler can access user preferences and must declare the permissions it needs. Users can manage all settings from The Butler's settings interface, and your Butler must respect these preferences and handle permission changes gracefully.
5. Action Delegation
The Butler's action delegation system routes user actions (e.g., "log expense", "add to list") to the right Butler. The Butler resolves intents and hands off to the appropriate Butler so one tap or command does the right thing. Your Butler can register actions it can handle and respond to intent queries with likelihood scores.
6. Navbar Configuration
The Butler provides navigation hooks that allow your Butler to control the shell's top bar and tab bar per context. Butlers can request titles, back behavior, and primary actions so the navigation feels native to each screen. Update navigation configuration when screen context changes to provide a seamless user experience.
7. Theme & Appearance Management
All Butlers must adhere to the appearance API provided by The Butler. The core shell manages theme preferences (light/dark mode), color schemes, and design tokens. Your Butler receives theme information through the JS Bridge and must respect user preferences for a consistent, native experience. Use design tokens and CSS custom properties for automatic theme support.
8. Data Request
Butlers are stateless and do not store user data directly. All data operations go through The Butler's Data API, which handles storage, permissions, and security. Your Butler can query, create, update, and delete data, and subscribe to data changes. The Butler enforces permissions and returns only what each Butler is allowed to see.
9. Event Pipeline
The Butler provides a central event bus for cross-Butler updates. When one Butler changes data (e.g., new expense, new reminder), others can subscribe and react—enabling automation and consistent state without tight coupling. Your Butler can publish events and subscribe to events from other Butlers to enable cross-Butler workflows.
10. Alerts
Alerts is a core navigation tab (4th item in the main navbar: Home, Tasks, Calendar, Alerts). Alerts are urgent but don't have a schedule—they appear contextually when needed. The Butler centralizes all alerts from all Butlers in one unified interface. All Butlers can create alerts through the Smart Alert Engine with priorities, actions, and user-controlled preferences.
11. Listen for Instructions
The Butler can listen to users for voice instructions. Say what you want (e.g., "log an expense", "add milk to the list") and The Butler routes it to the right Butler via action delegation—hands-free when you need it. Voice commands are processed through The Butler's intent resolution system and routed to the appropriate Butler based on likelihood scores.
Basic Integration
- Register your Butler: Register with Life Butler so it appears in the core navigation and can receive deep links.
- Use the JS Bridge: Call
requestData,callAPI,getAuthToken, and related methods. All network and storage go through the host app. - Follow navigation and UI guidelines: Use the provided layout hooks (header, back, tab bar) so your Butler feels native. Support theme and viewport from the shell. All Butlers must use the appearance API for consistent theming.
- Request only the scopes you need: Declare data categories and explain why in your Butler's permission screen. Users can revoke access anytime.
Integration Flow
Your Butler is loaded when the user opens it from The Butler's list. The shell injects the bridge and passes initial context (user, locale, theme). You render your UI using the appearance API for theming, call bridge methods for data, and send updates back for persistence. No backend required—Life Butler handles data and auth.
Coming Soon
Additional integration points in development: Home screen and lock screen widgets, Siri Shortcuts integration, Share Extension, Spotlight search integration, Apple Watch complications, Shortcuts app automation, custom analytics events, and data export integration.