RemoteCompanion: Scriptable iOS Automation
Detailed Description of RemoteCompanion: A Powerful Rootless Jailbreak Automation Tool for iOS
Introduction
RemoteCompanion is an advanced, scriptable automation tool designed specifically for jailbroken iOS devices running modern rootless jailbreaks (iOS 15 and later). It enables users to bind physical gestures, hardware buttons, NFC tags, Wi-Fi connections, or Bluetooth states to execute custom commands remotely via a computer terminal. Whether you want to control media playback, unlock your device, simulate button presses, or run complex automation sequences, RemoteCompanion provides an intuitive yet highly flexible system for seamless iOS interaction.
This guide explores its core features, workflows, and capabilities in depth, including its graphical user interface (GUI) components, CLI commands, Lua scripting integration, and advanced automation functionalities.
Core Features & Functionality
1. Instant Response with Optimized SSH-Tunneled Communication
RemoteCompanion leverages a high-speed command execution mechanism (~0.2 seconds latency) using optimized SSH-tunneled UNIX domain sockets. This ensures near-instantaneous responses when triggering actions from either the device itself or an external computer.
2. Smart Control & Multi-Step Action Sequences
Users can create and manage complex action sequences, edit existing commands inline, and control settings remotely without requiring physical access to the device. The system supports nested actions that reorder smoothly for efficient workflow management.
Graphical User Interface (GUI) Overview
(1) Main Interface (v2.3.0)
The primary dashboard of RemoteCompanion presents a sleek, modern interface with large titles and SF Symbols, aligning with iOS design aesthetics. Users can:
- Add new triggers by selecting hardware buttons, gestures, or NFC/Wi-Fi/Bluetooth states.
- Organize actions into logical sequences for quick execution.
- Test triggers via long-press interactions within the app.
Example of the RemoteCompanion main interface with trigger selection and action configuration.
(2) Action Picker & Trigger Configuration
The action picker allows users to select predefined commands (e.g., media controls, device unlocks, app launches) or create custom scripts. The system supports:
- Conditional actions ("If" blocks) – Introduced in v2.3, enabling smart automation where actions only execute under specific conditions.
- Hardware button bindings – Double-tap, long-press, triple-click, and volume combinations for Power/Volume buttons.
- Touch ID triggers – Single tap or hold gestures on the Home button.
Example of configuring a hardware trigger (e.g., double-tap Power button) to launch an app.
(3) Design Engine & Custom Scripting
RemoteCompanion’s design engine allows users to craft custom Lua scripts or call Objective-C methods via objc_call. This enables advanced automation, such as:
- Dynamic UI interactions – Automating app launches, media controls, and system settings.
- Custom hardware responses – Simulating button presses, adjusting brightness, or toggling Do Not Disturb (DND) based on user-defined logic.
Example of a Lua script action block for executing custom commands.
(4) Settings & Backup
The settings tab provides:
- Trigger favorites – Quick-access shortcuts for frequently used actions.
- App blacklist system – Managed via CLI, preventing triggers from firing while specific apps (e.g., banking or camera) are active.
- Backup & restore options – Exporting/importing configurations for easy migration between devices.
Example of the RemoteCompanion settings panel with backup and app blacklist management.
Key Functionalities
(A) Media & Volume Controls
RemoteCompanion supports a wide range of media automation commands, including:
- Play/Pause/Next/Previous – Directly control music or video playback via
rc play,rc pause, etc. - Volume adjustments – Set volume levels (0–100%) with
rc volume. - Mute toggling – Enable/disable media mute (
rc mute on/off/toggle). - Headphone ANC control – Requires Sonitus compatibility for advanced audio settings.
(B) Device Control
Users can perform system-level actions such as:
- Unlocking the device – Wake and unlock via
rc unlock. - Simulating hardware buttons – Press Power, Volume Up/Down, or Home button (
rc button). - Brightness & flashlight control – Adjust screen brightness (
rc brightness) or toggle the torch (rc flashlight). - Orientation lock toggling – Switch between portrait and landscape modes (
rc rotate).
(C) App Management
RemoteCompanion allows seamless app interactions, including:
- Launching apps by name/bundle ID – Open Spotify, Messages, or Settings via
rc open. - Force-quitting apps – Close apps like YouTube or Safari with
rc kill. - Shortcut execution – Run custom iOS Shortcuts (requires SpringCuts).
- URL opening – Launch web links (
rc url) or Spotify playlists (rc spotify).
(D) Connectivity & Bluetooth/Wi-Fi Management
Users can manage network and device connectivity via:
- Wi-Fi/Bluetooth toggling – Enable/disable connections (
rc wifi,rc bluetooth). - AirPlay discovery – List nearby AirPods or speakers (
rc airplay list) and connect to them. - Bluetooth pairing – Connect/disconnect devices dynamically.
(E) Hardware Triggers (Tweak App Configuration)
RemoteCompanion supports a variety of hardware triggers, including:
- Power/Volume buttons – Double-tap, long-press, or triple-click combinations.
- Home button gestures – Tap, hold, double/triple click.
- Touch ID sensor – Single tap or rest-finger detection.
- NFC tags – Scan physical NFC chips to trigger actions (optional toggle in settings).
- Ringer switch – Mute/unmute or toggle triggers based on volume state.
(F) Text & Notifications
Users can interact with the system via:
- Typing commands – Execute
rc typefor text input. - Pasting clipboard content – Use
rc paste. - Keyboard shortcuts – Simulate specific keys (e.g.,
0x04for 'A').
(G) Status & Query Commands
RemoteCompanion provides real-time device state checks via:
- Volume status – Retrieve current volume level (
rc volume). - App foreground detection – Get the active app’s bundle ID (
rc app). - Lock/unlock status – Check if the device is locked (
rc is-locked). - Media playback status – Determine if a song/playlist is playing, paused, or stopped.
- Orientation & DND status – Query portrait/landscape mode and Do Not Disturb settings.
Conditional Actions ("If" Blocks) in v2.3
One of the most significant improvements in RemoteCompanion v2.3 is the introduction of "If" blocks, allowing users to create smart automation sequences that only execute under specific conditions. For example:
- "If Wi-Fi is OFF, turn it back ON."
- "If Orientation is Landscape, toggle Flashlight."
This feature enhances flexibility by enabling nested actions that reorder seamlessly when editing.
Lua Scripting & Objective-C Bridge
RemoteCompanion supports Lua scripting for advanced automation, allowing users to:
- Run scripts from the CLI – Execute commands via
rc lua /path/to/script.lua. - Paste code directly in the app UI – Add custom Lua actions under "System" > "Custom Lua Script."
Example Lua Scripts
(1) Triggering Haptic Feedback & Logging
log("Starting haptic engine...")
haptic()
delay(0.2)
haptic()
log("Finished haptic feedback.")
This script logs a message, triggers a haptic response, and pauses briefly before repeating.
(2) Calling Objective-C Methods (e.g., Battery Level Check)
local device = objc_call("UIDevice", "currentDevice")
if device then
local level = objc_call(device, "batteryLevel")
log("Battery: " .. tostring(level * 100) .. "%")
end
This script retrieves the current battery percentage and logs it.
(3) Loading Private Frameworks
local ok = dlopen("/path/to/yourlibrary.dylib")
if ok then
local instance = objc_call("YourClass", "sharedInstance")
if instance then
objc_call(instance, "yourMethod")
end
end
This example loads a dynamic library and calls a method on an Objective-C class.
Blacklist System (App Exclusion)
RemoteCompanion includes an app blacklist to prevent conflicts between hardware triggers and apps that use similar gestures or buttons. Users can:
- Add/remove apps via CLI commands (
rc blacklist add,rc blacklist remove). - Manage the list with
rc blacklist list. - Reset defaults using
rc blacklist reset.
This ensures smooth operation even when running games, camera apps, or other resource-intensive applications.
Command Line Interface (CLI) Usage
RemoteCompanion can be controlled entirely via terminal commands, making it ideal for automation in Home Assistant or custom scripts. Below are key CLI workflows:
(1) Basic Setup & Installation
- Copy the
rcscript to/usr/local/bin/:
chmod +x rc
sudo cp rc /usr/local/bin/rc
- Set your iPhone’s IP in
.zshrc(or equivalent shell config):
export RC_IPHONE_IP=iphone.local
- Run commands directly:
rc play # Plays the next track
(2) SSH Direct Control
For secure remote execution:
ssh mobile@iphone.local "rc lock"
ssh mobile@iphone.local "rc volume 50"
(3) Home Assistant Integration
Configure a shell command in YAML to execute rc commands dynamically:
shell_command:
iphone_remote: ssh -o StrictHostKeyChecking=no mobile@YOUR_IPHONE_IP "rc {{ cmd }}"
Call it via:
service: shell_command.iphone_remote
data:
cmd: 'play'
Advanced Automation & Workflows
(A) NFC Tag Triggers
Users can bind actions to physical NFC tags for quick device control. For example:
- Scan an NFC tag to launch Spotify.
- Trigger a custom script when entering a specific location.
(B) Bluetooth/Wi-Fi State Awareness
RemoteCompanion can detect Wi-Fi/Bluetooth states and execute commands accordingly, such as:
if objc_call("WifiManager", "isConnected") == false then
rc wifi on
end
(C) Orientation-Aware Automation
Example: Toggle the flashlight when switching between portrait and landscape modes.
if orientation_status == "LANDSCAPE" then
rc flashlight toggle
end
Security & Compatibility Considerations
(1) Local Access Only
RemoteCompanion ensures secure communication by restricting access to local UNIX sockets, preventing network exposure.
(2) iOS 14 arm64e (A12+) Limitations
- Unsupported: iOS 14 on A12+ devices due to Pointer Authentication Code (PAC) changes.
- Workaround: Compile the tweak using Xcode 15.4 or earlier for compatibility.
(3) Apple Pay & NFC Conflicts
If experiencing issues with Apple Pay, disable NFC scanning in RemoteCompanion settings to prevent conflicts.
Getting Started: Installation & Setup
(1) Requirements
- A jailbroken iOS device (iOS 14+).
- Supports both rootless (iOS 15+) and rootful (iOS 14) environments.
- The
RemoteCompaniontweak installed.
(2) Installation Options
Option 1: Repository (Recommended)
Add the following to Sileo or Zebra:
- Zebra: zbra://sources/add/https://saihgupr.github.io/remotecompanion
- Sileo:
sileo://source/https://saihgupr.github.io/remotecompanion
Option 2: Manual Install
Download the .deb package from GitHub Releases.
Option 3: Build from Source
cd Tweak && make package install
Troubleshooting Common Issues
(1) Apple Pay & NFC Scanning Conflicts
- Go to the Settings tab in RemoteCompanion.
- Disable "NFC Scanning" to prevent conflicts with system services.
(2) Safe Mode Loop on iOS 14 (A12+)
If using an older tweak compiler, ensure compatibility by compiling with Xcode 15.4 or earlier.
Conclusion
RemoteCompanion is a versatile and powerful tool for jailbroken iOS users seeking advanced automation capabilities. Whether you want to control media playback, simulate hardware interactions, or execute complex Lua scripts, RemoteCompanion provides an intuitive GUI and robust CLI support. Its conditional actions, NFC/Wi-Fi/Bluetooth triggers, and app blacklist system make it ideal for both casual users and power automation enthusiasts.
By leveraging its high-speed SSH-tunneled communication and cross-version compatibility (iOS 14–16+), RemoteCompanion remains a reliable choice for seamless iOS device management in rootless environments. For further customization, exploring Lua scripting and Objective-C integration opens up endless possibilities for personalized automation workflows.
Final Note: Always ensure your device is jailbroken securely and keep the tweak updated to access the latest features and bug fixes.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.
Repository:https://github.com/saihgupr/remotecompanion
GitHub - saihgupr/remotecompanion: RemoteCompanion: Scriptable iOS Automation
RemoteCompanion is an advanced, scriptable automation tool designed specifically for jailbroken iOS devices running modern rootless jailbreaks (iOS 15 and later...
github - saihgupr/remotecompanion