diff --git a/loop.sh b/loop.sh
index 744e11e..771b9a5 100755
--- a/loop.sh
+++ b/loop.sh
@@ -81,6 +81,23 @@ if ! command -v jq &>/dev/null && ! command -v python3 &>/dev/null; then
     exit 1
 fi
 
+# --- macOS timeout compatibility ---
+# macOS doesn't have GNU timeout. Use gtimeout (from coreutils) or a perl fallback.
+if ! command -v timeout &>/dev/null; then
+    if command -v gtimeout &>/dev/null; then
+        timeout() { gtimeout "$@"; }
+    else
+        # Perl-based fallback: runs command with alarm signal
+        timeout() {
+            local duration="$1"; shift
+            perl -e '
+                alarm shift @ARGV;
+                exec @ARGV;
+            ' "$duration" "$@"
+        }
+    fi
+fi
+
 # --- Load config defaults ---
 CONFIG_FILE="$LOOP_DIR/config.json"
 config_default() { get_config_value "$1" "$2"; }