ProximityShortcuts User Guide

What is ProximityShortcuts?

ProximityShortcuts is a macOS menu bar app that automatically triggers shortcuts based on the proximity of your iPhone, Apple Watch, or any other Bluetooth device you carry with you, such as fitness bracelets, smart rings, or BLE tags. When your device moves away from your Mac, it can run shortcuts like locking your screen, pausing music, or turning off lights. When you return, it can resume playback, turn lights back on, and so on.

Think of it as "presence detection" for your Mac - it knows when you're nearby and when you've left, then takes actions you define.

Quick Start

1. First Launch

1. Launch ProximityShortcuts from Applications
2. Click the menu bar icon (multiple circles with dot inside)
3. Click "Continue" to grant Bluetooth permission
4. Wait a few seconds for devices to appear

2. Select Your Device

1. Choose your iPhone or Apple Watch from the list
2. The app will start monitoring its proximity
3. Watch the signal graph to see real-time signal strength

3. Configure Actions

1. Click the gear icon (⚙️) to open Settings
2. Enable "Device Went Away" and enter a shortcut name
3. Enable "Device Is Back" and enter a shortcut name
4. Create these shortcuts in the macOS Shortcuts app

4. Test It

1. Walk away from your Mac with your device
2. After a few seconds, your "away" shortcut will run
3. Return to your Mac
4. Your "back" shortcut will run

How It Works

Bluetooth Signal Monitoring

ProximityShortcuts uses Bluetooth Low Energy (BLE) to continuously monitor the signal strength (RSSI) from your iPhone or Apple Watch. The signal strength indicates how close your device is:

• Strong signal (-30 to -50 dBm): Device very close (on desk, in pocket)
• Medium signal (-50 to -70 dBm): Device nearby (across room)
• Weak signal (-70 to -90 dBm): Device far away (different room)
• No signal (-100+ dBm): Device out of range or powered off

Signal Processing

The app uses advanced signal processing to distinguish between:

• You walking away: Gradual signal degradation
• Normal movement: Small signal fluctuations (wrist movement, shifting in chair)
• Temporary interference: Brief signal drops that recover quickly
• Device powered off: Sudden signal loss without degradation

This prevents false triggers when you're just moving around normally.

State Machine

The app tracks three device states:

1. Present (Green dot): Device is in range with good signal
2. Weak Signal (Red dot): Signal is degrading but device still detected
3. Absent (Red dot): Device is out of range or signal lost

Note: Both Weak Signal and Absent states show a red indicator. The difference is internal - Weak Signal means the device is still being detected but below threshold, while Absent means no signal is received at all.

Shortcuts are triggered when transitioning between these states, with configurable delay to further prevent false triggers.

Setup Guide

Prerequisites

• macOS 14.0 or later
• A Bluetooth device to carry with you. iPhone or Apple Watch signed in with the same Apple ID as your Mac work best, but other Bluetooth devices you keep on you (fitness bracelets, smart rings, BLE tags, AirPods, etc.) may also work.
• Bluetooth enabled on your Mac
• macOS Shortcuts app

Initial Configuration

1. Grant Bluetooth Permission

On first launch, you'll see a permission screen. Click "Continue" to grant permission. If you accidentally deny permission, you can grant it later in System Settings > Privacy & Security > Bluetooth.

2. Select Your Device

After granting permission, you'll see a list of nearby Bluetooth devices:

• iPhone: Usually shows as "Your Name's iPhone"
• Apple Watch: Usually shows as "Your Name's Apple Watch"
• Other devices: AirPods, keyboards, mice, etc.

Tip: Can't see your device? Make sure it's signed in with the same Apple ID as your Mac, Bluetooth is enabled, within range (same room), and not in Airplane Mode.

3. Adjust Proximity Threshold

The proximity threshold determines how close your device needs to be to be considered "present":

• Slider position: Drag left for less sensitive (device can be farther), right for more sensitive (device must be closer)
• Current value: Shows in dBm (e.g., "-65 dBm")
• Real-time feedback: Green dot = device present, red dot = device absent

Recommended starting point: -65 dBm (default)

4. Set Action Delay

The action delay is how long to wait before executing shortcuts after detecting a state change:

• Slider position: 1 to 90 seconds
• Purpose: Prevents false triggers from brief signal drops
• Recommended: 15 seconds for most users

Example: If set to 15 seconds, when you walk away, the app waits 15 seconds to confirm you're really gone before running the "away" shortcut.

Need a longer delay? Click the # icon next to the slider to switch to a manual minutes + seconds input. This bypasses the 90-second slider maximum and lets you set delays up to roughly 3 hours.

5. Enable Auto-Adjust (Optional)

Auto-adjust automatically learns your device's typical signal strength and optimizes the threshold. See Advanced Features for details.

Features & Settings

Main Window

Device Status Section (Top)

• Status indicator: Green/orange/red dot showing device state
• Device name: Currently selected device
• Signal strength: Current RSSI in dBm
• Signal graph: Real-time visualization of signal strength over time

Device List Section (Middle)

• Available devices: All discovered Bluetooth devices
• Selection: Click checkbox to select a device
• Auto-refresh: List updates automatically as devices appear/disappear

Controls Section (Bottom)

• Proximity threshold slider: Adjust the signal strength (in dBm) at which the device is considered "present". Drag left for less sensitive (device can be farther), right for more sensitive (device must be closer). Default -65 dBm.
• Action delay slider: How long to wait before executing shortcuts after detecting a state change. Range 1 to 90 seconds, default 15s. Prevents false triggers from brief signal drops.
• Custom delay input: Click the # icon next to the slider to switch from the slider to manual minutes + seconds fields. This lets you set delays longer than the 90-second slider maximum, up to about 3 hours. Click the slider icon to switch back.
• Profile picker: Quick profile switcher dropdown showing the active profile (or "Custom"). See Settings Profiles.
• Settings (gear ⚙️) button: Opens the Settings panel where Launch at Login, Shortcut actions, Advanced Settings, and Settings Profiles live
• Quit button: Exits the app entirely

Settings Panel

Click the gear icon (⚙️) to access settings:

Launch at Login

Toggle: Start ProximityShortcuts automatically when you log in. Recommended - Enable so you don't have to manually launch the app each time you restart your Mac.

Shortcut Actions

Groups the two proximity-triggered shortcuts: Device Went Away and Device Is Back. Each can be enabled independently and configured with its own shortcut name and skip conditions.

Device Went Away

Run a shortcut when your device goes out of range.

• Toggle: Enable/disable away shortcut
• Shortcut name field: Inline text field where you enter the exact name of the shortcut to run (case-sensitive, must match a shortcut in macOS Shortcuts app)
• Skip when screen is locked: Prevent execution if Mac is already locked
• Do not run when signal was strong and stable, then suddenly disappeared (e.g., device powered off, strong interference): Helps to avoid false positives. Shortcuts will still execute when signal gradually degrades (walking away).

Device Is Back

Run a shortcut when your device comes back in range.

• Toggle: Enable/disable back shortcut
• Shortcut name field: Inline text field where you enter the exact name of the shortcut to run (case-sensitive, must match a shortcut in macOS Shortcuts app)
• Skip when screen is locked: Prevent execution if Mac is locked

Advanced Settings (Kalman, Auto-threshold)

A collapsible section that contains all fine-tuning controls. Click the chevron to expand. Contains four groups: Kalman Filter Presets, Auto-adjust Action Threshold, Hysteresis Band, and Shortcut Oscillation Cooldown.

Kalman Filter Presets

ProximityShortcuts uses Kalman filtering to distinguish genuine movement from signal noise. These presets control how aggressively the filter balances detection speed vs reliability:

• Responsive: Reacts immediately to signal changes. Best when you need quick responses, but may occasionally trigger on brief interference or signal fluctuations.
• Balanced (Recommended): Filters out most signal noise while maintaining good responsiveness. Good for typical everyday use.
• Stable: Heavily filters signal noise, requiring clear and sustained changes before acting. Prevents false triggers but takes longer to react.

Tip: Start with Balanced. If you experience false triggers from brief interference, switch to Stable. If detection feels too slow, try Responsive.

Auto-adjust Action Threshold

Automatically learns and adapts the threshold to your device's typical signal strength. See Auto-Adjust Feature for the full explanation of how learning works.

• Enable Auto-Adjust toggle: Turn automatic threshold learning on or off
• Maximum Threshold allowed slider (-85 to -30 dBm): Strongest signal boundary allowed. Prevents auto-threshold from being set so strong that there's no room for reliable detection.
• Minimum Threshold allowed slider (-85 to -40 dBm): Weakest signal allowed (device likely absent beyond this). Prevents auto-threshold from being set too weak.

Aggressiveness slider (Tolerant ↔ Strict): When Auto-Adjust is enabled, the main window's threshold slider is replaced by an aggressiveness slider that controls how quickly the threshold adapts to your device's signal patterns.

Note: The app enforces a minimum 5 dBm separation between the min and max bounds. Adjusting one slider automatically caps the other to maintain this gap.

Hysteresis Band

Prevents shortcuts from triggering repeatedly when signal fluctuates near the threshold by requiring a larger change before switching between "away" and "back" states.

• Return Threshold Offset slider (0-15 dBm, prefixed with +): Signal must exceed threshold + offset to return to Present state
• Away Threshold Offset slider (0-15 dBm, prefixed with -): Signal must drop below threshold - offset to transition Away
• Show Hysteresis Zone on Graph toggle: Visualize the dead-band region on the signal graph

Shortcut Oscillation Cooldown

Minimum time between opposite shortcut executions. Prevents an away shortcut from immediately firing after a back shortcut (or vice versa) when the device hovers near the threshold.

• Cooldown slider (1-180 seconds, default 15s): Lower values let away and return shortcuts run again sooner

Settings Profiles

Settings Profiles allow you to save and quickly switch between different monitoring configurations. Perfect for managing multiple scenarios like "Work", "Home", or "Travel" without manually reconfiguring all settings each time.

What Are Profiles?

A profile saves all your current settings including:

• Proximity threshold and action delay
• Auto-threshold configuration (enabled, aggressiveness, min/max bounds)
• Detection mode (Responsive/Balanced/Stable)
• Shortcut actions (away/back shortcuts and their names)
• Shortcut preferences (screen lock prevention, sudden signal loss detection)
• Action delays for away/back shortcuts

Creating a Profile

1. Configure your settings exactly how you want them for this scenario
2. Click Settings (gear icon)
3. Scroll to Settings Profiles section
4. Click Create New button
5. Enter a profile name (e.g., "Work", "Home")
6. Optionally add a description
7. Click Create

Managing Profiles

Profile Row Controls

Each profile in the Settings Profiles list has the following controls:

• Apply button: Instantly applies that profile's settings to the app
• ⋮ menu button: Opens a menu with Edit (rename / change description), Duplicate (create a copy with " Copy" suffix), and Delete
• Active badge: Indicates which profile's settings are currently applied
• Save button: Appears on the active profile when you've modified settings since applying it. Click to update the profile with your current settings.

Create New Button

Located at the top-right of the Settings Profiles section. Opens a sheet where you enter a name and optional description, then captures your current settings as a new profile.

Default Profile Protection

The "Default" profile is automatically created on first launch and is protected:

• Cannot be deleted (protected system profile)
• Can be modified (Save button updates it)
• Can be duplicated via the ⋮ menu if you want a starting point for a new profile

Quick Profile Switcher (Main Window)

The main popover includes a quick profile picker below the device list:

• Shows the current profile name (or "Custom")
• Click to see a dropdown with all profiles
• Select a profile to instantly apply it
• Click ⚙️ Manage… at the bottom of the dropdown to open Settings

Switching Profiles

From Main Window: Click the Profile dropdown (below device list) and select the profile you want to apply. All settings instantly change to match that profile.

From Settings Panel: Find the profile in the list and click the Apply button.

Example Use Cases

Understanding the Interface

Signal Graph

The signal graph shows real-time signal strength over the last ~40 seconds:

• Blue line: Filtered signal strength (smoothed for stability)
• Orange dashed line: Current proximity threshold
• Y-axis: Signal strength in dBm (higher = stronger)
• X-axis: Time (right = most recent)

Reading the graph:

• Line above orange threshold = Device present (green indicator)
• Line below orange threshold = Device weak/absent (red indicator)
• Steep downward slope = Walking away
• Steep upward slope = Approaching
• Flat line = Stable signal

Status Indicators

Green Dot - Device Present

• Signal is above threshold
• Device is in range
• "Back" shortcuts can trigger when transitioning from weak/absent

Red Dot - Weak Signal or Absent

• Weak Signal: Signal is below threshold but still detected (transitional state)
• Absent: No signal detected or very weak signal (device out of range)
• "Away" shortcuts can trigger when transitioning from present to weak/absent

Orange Dot - Bluetooth Off

• Special indicator when Bluetooth is disabled on your Mac
• Enable Bluetooth in System Settings to use the app

Creating Shortcuts

ProximityShortcuts triggers shortcuts you create in the macOS Shortcuts app. Here's how to create effective shortcuts:

Opening Shortcuts App

1. Open Spotlight (⌘ + Space)
2. Type "Shortcuts"
3. Press Enter

Or find it in Applications folder.

Example: Lock Screen When Away

1. In Shortcuts app, click "+" to create new shortcut
2. Name it "Lock Screen" (or whatever you entered in ProximityShortcuts settings)
3. Search for "Lock Screen" action
4. Drag it into your shortcut

Example: Smart Home Integration

Turn off lights when away:

1. Create shortcut named "Lights Off"
2. Add "Toggle Accessory or Scene" action (HomeKit)
3. Choose your "Away" scene

Testing Shortcuts

Before using with ProximityShortcuts:

1. Run the shortcut manually in Shortcuts app
2. Verify it does what you expect
3. Check for any permission prompts
4. Grant necessary permissions

Important: Shortcuts must be named exactly as entered in ProximityShortcuts settings (case-sensitive).

Troubleshooting

Device Not Appearing in List

Possible causes:

1. Device not signed in with same Apple ID
2. Bluetooth disabled on device
3. Device in Airplane Mode
4. Device too far away

Solutions:

1. Verify Apple ID on both devices
2. Enable Bluetooth in device settings
3. Disable Airplane Mode
4. Move device closer to Mac
5. Wait 30 seconds for scan to complete

Shortcuts Not Executing

Check these:

1. Shortcut name matches exactly - Open Shortcuts app, verify name matches what you entered in settings (case-sensitive)
2. Shortcut works manually - Run shortcut in Shortcuts app, fix any errors before using with ProximityShortcuts
3. Permissions granted - Some shortcuts need permissions (HomeKit, Music, etc.), run manually first to grant permissions
4. Screen lock prevention - If "Skip when screen is locked" is enabled, shortcuts won't run when Mac is locked

False Triggers

Symptoms: Away shortcut runs when you're still at desk, or back shortcut runs when you haven't returned.

Solutions:

1. Increase action delay - Settings → Action delay slider, try 20-30 seconds instead of 15
2. Adjust threshold - Make it less sensitive (move slider left) or enable auto-adjust
3. Enable "Skip on sudden signal loss" - Settings → Device Went Away → Enable to prevent false triggers from interference
4. Check signal graph - Watch the graph while moving around to ensure threshold is appropriate

Advanced Features

Auto-Adjust Feature

Auto-adjust automatically optimizes the proximity threshold based on your device's typical signal strength.

How It Works

1. Learning Phase - Collects signal samples while the device is present until enough samples have been gathered. A "Learning..." status is shown during this phase.
2. Calculation - Analyzes the collected samples, selects an appropriate percentile based on the aggressiveness slider position, and adds a safety buffer.
3. Continuous Adaptation - Maintains a rolling window of recent signal history and periodically recalculates the threshold to adapt to changing conditions. The window length and update frequency depend on the aggressiveness slider (see below).

Aggressiveness Slider

Controls how aggressively the threshold adapts to your device's signal:

Signal Loss Classification

The app can distinguish between different types of signal loss:

• Sudden Signal Loss: Signal was strong and stable, then suddenly disappeared. Likely causes: Device powered off, interference, Bluetooth issue. Not caused by walking away.
• Gradual Signal Loss: Signal showed declining trend, degraded over several seconds. Likely cause: Walking away with device.

Enable "Skip on sudden signal loss" to prevent away shortcuts from running when signal disappears suddenly. Recommended if you experience false triggers from temporary Bluetooth issues.

Best Practices

Device Selection

iPhone vs Apple Watch:

• iPhone: Stronger, more stable signal. Better for desk/pocket scenarios. Faster detection. May not always be with you.
• Apple Watch: Always on your wrist. More reliable presence indicator. Often weaker, more variable signal. Needs auto-adjust set to Tolerant mode.

Recommendation: Use iPhone if it's always with you (move the auto-adjust aggressiveness slider toward Strict for steadier detection). Use Apple Watch if you always wear it (move the slider toward Tolerant to handle signal variations).

Threshold Configuration

Start with defaults:

1. Use -65 dBm threshold
2. Use 15-second action delay
3. Enable auto-adjust after testing

Adjust based on experience:

• Too many false triggers → Increase delay or enable "Skip on sudden signal loss"
• Too slow to detect → Decrease delay or adjust threshold
• Signal varies a lot → Enable auto-adjust with "Tolerant" setting

Shortcut Design

Keep shortcuts simple:

• Single action shortcuts are most reliable
• Test shortcuts manually before using
• Avoid shortcuts that require user interaction

Privacy & Security

ProximityShortcuts only requires Bluetooth access on your Mac. All processing happens locally - no data is stored or sent anywhere. The app runs in macOS sandbox with restricted permissions, only having access to Bluetooth. All processing happens locally on your Mac.

FAQ

General Questions

Technical Questions

Profile Questions

Troubleshooting Questions

Support & Resources

Reporting Issues

When reporting issues, include:

1. macOS version
2. Device type (iPhone/Watch model)
3. Steps to reproduce
4. Relevant log messages from Console app
5. Screenshots if applicable

For support inquiries, email [email protected]

Learning More

About Bluetooth Low Energy:
Bluetooth SIG - BLE Overview

About macOS Shortcuts:
Apple Support - Shortcuts User Guide

Appendix

RSSI Reference Chart

Default Settings

System Requirements

• macOS: 14 or later
• Device: any Bluetooth device you carry with you. iPhone or Apple Watch (with iOS or watchOS 14 or later) work best, but fitness bracelets, smart rings, BLE tags, AirPods, and similar accessories may also work.
• Shortcuts: macOS Shortcuts app (pre-installed)

Glossary

BLE (Bluetooth Low Energy)

Low-power version of Bluetooth designed for IoT devices and continuous monitoring.

dBm (Decibel-milliwatts)

Unit of measurement for signal strength. Higher (less negative) values indicate stronger signals.

RSSI (Received Signal Strength Indicator)

Measurement of Bluetooth signal strength in dBm.

Kalman Filter

Mathematical algorithm that smooths noisy sensor data to provide stable, accurate readings.

Threshold

The RSSI value that determines whether a device is considered "present" or "absent".

Profile

Saved configuration containing all app settings that can be quickly applied.