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.

Action Picker 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.

Design Engine 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.

Settings & Backup 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 type for text input.
Pasting clipboard content – Use rc paste.
Keyboard shortcuts – Simulate specific keys (e.g., 0x04 for '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 rc script 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 RemoteCompanion tweak 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.

RemoteCompanion: Scriptable iOS Automation