iOS

​

Overview

• Gateway connection - connects to your SimpleClaw Gateway via WiFi or cellular
• Chat interface - text conversations with your assistant
• Voice Wake - hands-free voice activation
• Talk Mode - voice conversations with audio responses
• Camera access - photo and video capture
• Screen recording - capture screen content
• Location services - share device location
• Canvas - view and interact with agent-controlled web content
• Share extension - forward content from other apps

​

System Requirements

• iOS 15.0 or later
• Xcode 16+ (for building from source)
• Apple Development signing profile
• Connected to same network as SimpleClaw Gateway (for discovery)

​

Installation

​

Prerequisites

1. Xcode 16 or later - Install from the Mac App Store
2. pnpm - Package manager: npm install -g pnpm
3. xcodegen - Project generator: brew install xcodegen
4. Apple Developer account - Free or paid account for signing

​

Build and Deploy

# Install dependencies
pnpm install

# Configure signing
./scripts/ios-configure-signing.sh

# Generate Xcode project
cd apps/ios
xcodegen generate

# Open in Xcode
open SimpleClaw.xcodeproj

pnpm ios:open

​

Xcode Setup

1. Connect your iPhone via USB
2. Select SimpleClaw scheme
3. Select your iPhone as destination (real device recommended)
4. Select Debug build configuration
5. Click Product > Run (⌘R)

​

Signing Configuration

1. Copy apps/ios/LocalSigning.xcconfig.example to apps/ios/LocalSigning.xcconfig
2. Edit LocalSigning.xcconfig with unique bundle IDs
3. Rebuild the project

​

Features

​

Gateway Connection

• Automatic discovery via Bonjour/mDNS
• Shows available gateways on local network
• One-tap connection

• Specify gateway host and port
• TLS fingerprint trust prompt
• Supports remote gateways

1. Open the app and navigate to Connect
2. Enter setup code from gateway
3. Approve pairing on gateway:
   simpleclaw nodes pending
   simpleclaw nodes approve <requestId>
   

​

Chat & Talk

• Chat - send text messages to your assistant
• Talk - push-to-talk voice input with audio responses
• Session management - view conversation history
• Threading - replies maintain context

​

Camera & Screen

• camera.snap - capture still photos
• camera.clip - record short video clips with optional audio

• screen.record - capture screen content
• Requires Screen Recording permission

• Camera (for photo/video)
• Microphone (for video with audio)
• Screen Recording (for screen capture)

​

Location Services

• One-time location - current location on request
• Significant location changes - movement-based updates
• Background location - requires “Always” permission

• Arrival/exit geofence triggers
• Significant movement detection
• Visit detection

​

Canvas

• WebKit-based rendering
• JavaScript evaluation
• Navigation control
• Snapshot capture

• canvas.present - show content
• canvas.navigate - load URL
• canvas.eval - run JavaScript
• canvas.snapshot - capture screenshot

​

Share Extension

1. Open content in any app (Safari, Photos, etc.)
2. Tap Share button
3. Select SimpleClaw
4. Content is forwarded to your gateway session

​

Permissions

​

APNs Push Notifications

• Development builds - APNs sandbox environment
• Release builds - APNs production environment
• Registration - happens after gateway connection
• Token sharing - device token sent to gateway via push.apns.register

• Push Notifications capability enabled
• Correct provisioning profile
• Valid bundle ID in Apple Developer portal

​

Background Behavior

​

Background Limitations

• WebSocket connections may be suspended
• These commands are blocked: canvas.*, camera.*, screen.*, talk.*
• Location updates require “Always” permission
• Background refresh may wake the app periodically

​

Wake & Reconnect

• Returning to foreground
• Receiving APNs silent push
• Background app refresh trigger
• Significant location change

​

Known Issues

• Background reliability - foreground use is most reliable
• Socket suspension - iOS may suspend background connections
• Command limits - many commands blocked when backgrounded
• Voice Wake conflicts - Talk Mode suppresses wake capture while active
• APNs reliability - depends on correct signing/provisioning
• Reconnect churn - expect occasional reconnect during active development

​

Debugging

​

Build Issues

1. Regenerate project: xcodegen generate
2. Verify team and bundle IDs in Xcode
3. Check signing certificate selection
4. Clean build folder: Product > Clean Build Folder

​

Connection Issues

1. Check Settings > Gateway for status
2. Verify gateway is running and reachable
3. Check firewall and network settings
4. Try manual connection with host/port

​

Pairing Issues

1. Run /pair approve from Telegram/WhatsApp
2. Check gateway logs for pairing requests
3. Verify setup code is correct
4. Reconnect after approval

​

Discovery Issues

1. Enable Discovery Debug Logs in Settings
2. Check Settings > Gateway > Discovery Logs
3. Verify both devices on same network
4. Check firewall allows mDNS/Bonjour

​

Xcode Console

• ai.simpleclaw.ios - app logs
• GatewayDiag - gateway diagnostics
• APNs registration failed - push notification errors

​

Development

​

Project Structure

apps/ios/
├── Sources/                   # Swift source files
│   ├── SimpleClaw.entitlements  # App capabilities
│   ├── Info.plist             # App metadata
│   ├── SimpleClawApp.swift    # App entry point
│   ├── Model/                 # App models
│   ├── Gateway/               # Gateway connection
│   ├── Voice/                 # Voice Wake and Talk
│   ├── Screen/                # Screen recording
│   ├── Services/              # Device services
│   └── ...
├── Tests/                     # Unit tests
├── WatchApp/                  # Apple Watch companion
├── WatchExtension/            # Watch extension
├── project.yml                # XcodeGen config
└── fastlane/                  # Build automation

​

Running Tests

cd apps/ios
xcodebuild test -scheme SimpleClaw -destination 'platform=iOS Simulator,name=iPhone 15'

​

Related Documentation

• Nodes
• Voice Wake
• Talk Mode
• Gateway Configuration