# Alfred Mobile

Android companion app for OpenClaw, providing voice interaction, push notifications, and mobile access to your AI assistant.

## Features

- **OAuth2 Authentication**: Secure login via Authentik
- **Voice Interaction**: Wake word detection, voice input, TTS responses
- **Push Notifications**: Receive alerts and alarms
- **Per-User Customization**: Custom assistant names and voices
- **Configurable Gateway**: Connect to any OpenClaw instance
- **Foreground Service**: Persistent connection for real-time messaging

## Setup

### Prerequisites

- Android Studio Arctic Fox or newer
- Android SDK 26+ (target 34)
- JDK 17
- Firebase project (for push notifications)

### Configuration

1. **Clone the repository**

2. **Create `secrets.properties` in project root:**
   ```properties
   GATEWAY_URL=wss://your-gateway-url.com
   AUTHENTIK_URL=https://auth.yourdomain.com
   AUTHENTIK_CLIENT_ID=your-oauth-client-id
   OAUTH_REDIRECT_URI=alfredmobile://oauth
   ELEVENLABS_API_KEY=your-elevenlabs-key (optional)
   ELEVENLABS_VOICE_ID=your-voice-id (optional)
   ```

3. **Add Firebase configuration:**
   - Download `google-services.json` from Firebase Console
   - Place in `app/` directory

4. **Build:**
   ```bash
   ./gradlew assembleDebug
   ```

### First Run

On first launch, the app will prompt for:
1. **Gateway URL**: Your OpenClaw/alfred-proxy WebSocket URL
   - Example: `alfred.yourdomain.com`
   - Protocol (wss://) is added automatically
   - Optional checkbox for insecure (ws://) connections

2. **OAuth Login**: Authenticate via your OAuth provider

3. **Permissions**: Grant microphone access for voice input

## Features

### Voice Interaction

- **Wake Word**: "Alfred" (customizable)
- **Voice Input**: Hold button or use wake word
- **TTS**: ElevenLabs integration with customizable voices

### Notifications

- **Push Notifications**: Via FCM
- **Alarms**: Full-screen alarm activity with dismiss/snooze
- **Cross-device Sync**: Dismissing on one device dismisses on all

### Customization

Settings → Customize:
- **Gateway URL**: Change server connection
- **Assistant Name**: Personalize (e.g., "Jarvis", "KITT")
- **Voice**: Choose from ElevenLabs voices
- **Alarm Sound**: Custom ringtone
- **Wake Word**: (coming soon)

### Multi-User Support

Each OAuth user gets:
- Separate preferences
- Custom assistant name
- Individual voice selection
- Private conversation history

## Architecture

```
Alfred Mobile App
    ↓ (OAuth JWT)
alfred-proxy (validates & routes)
    ↓ (OpenClaw token)
OpenClaw Gateway
    ↓
Agent Session (per user)
```

## Security

### Protected Files (.gitignore)

- `secrets.properties` - API keys and OAuth config
- `app/google-services.json` - Firebase config
- `*.keystore` - Signing keys
- `*.jks` - Signing keys

**Never commit these files!**

### OAuth Flow

1. App redirects to Authentik
2. User authenticates
3. App receives OAuth code
4. Exchanges code for access token
5. Token used for all gateway requests

## Development

### Build Variants

```bash
# Debug build (uses BuildConfig secrets)
./gradlew assembleDebug

# Release build (requires signing config)
./gradlew assembleRelease
```

### Install

```bash
# Via ADB
adb install -r app/build/outputs/apk/debug/app-debug.apk

# Wireless ADB
adb connect <device-ip>:5555
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

### Debugging

```bash
# View logs
adb logcat -s Alfred:D GatewayClient:D TTSManager:D

# Clear app data (reset first-run)
adb shell pm clear com.openclaw.alfred
```

## Dependencies

Key libraries:
- **Jetpack Compose**: UI framework
- **Dagger Hilt**: Dependency injection
- **OkHttp**: WebSocket client
- **Firebase**: Cloud Messaging
- **Vosk**: Wake word detection
- **AppAuth**: OAuth2 client

See `app/build.gradle.kts` for full list.

## Contributing

When submitting PRs:
1. Never commit secrets or credentials
2. Test on both tablet and phone form factors
3. Verify OAuth flow on fresh install
4. Check voice/TTS on long responses

## Roadmap

- [ ] Custom wake word training
- [ ] Offline mode with cached responses
- [ ] Widget support
- [ ] Android Auto integration
- [ ] Wear OS companion app

## License

MIT

## Security Notice

This app handles OAuth tokens and has microphone access. Ensure:
- HTTPS/WSS only for production
- Validate OAuth redirect URIs
- Keep Firebase credentials secure
- Request minimum necessary permissions