Cron-Based Task Scheduling

How PhoneClaw schedules and executes automation tasks using cron expressions

Overview

PhoneClaw includes a cron-based task scheduler that enables automation scripts to run on recurring schedules. This allows you to automate posting, data scraping, monitoring, and other tasks without manual intervention.

Architecture

Data Model

From MainActivity.kt:152-159:

data class CronTask(
    val id: String,
    val taskDescription: String,
    val cronExpression: String,
    val createdAt: Long = System.currentTimeMillis(),
    var lastExecuted: Long = 0L,
    var isActive: Boolean = true
)

Fields:

• id: Unique UUID for the task
• taskDescription: JavaScript code or human-readable description
• cronExpression: Cron schedule (simplified format)
• createdAt: Timestamp when task was created
• lastExecuted: Last execution timestamp
• isActive: Whether task should run

Scheduler Implementation

PhoneClaw uses Kotlin coroutines for lightweight background scheduling:

private val cronScheduler: ScheduledExecutorService = Executors.newScheduledThreadPool(2)
private var cronCheckJob: Job? = null
private val cronTasks = mutableMapOf<String, CronTask>()

Starting the Scheduler

From MainActivity.kt:3497-3520:

private fun startCronChecker() {
    cronCheckJob?.cancel()
    
    cronCheckJob = mainScope.launch {
        Log.d("MainActivity", "Cron checker started")
        
        while (isActive && !isDestroyed) {
            try {
                checkAndExecuteCronTasks()
                
                // Check every 60 seconds
                delay(60000)
            } catch (e: CancellationException) {
                Log.d("MainActivity", "Cron checker cancelled")
                throw e
            } catch (e: Exception) {
                Log.e("MainActivity", "Error in cron checker: ${e.message}")
                delay(60000)
            }
        }
    }
}

The scheduler checks every 60 seconds to see if any tasks should execute. This provides minute-level scheduling precision.

Task Execution Logic

From MainActivity.kt:3521-3555:

private suspend fun checkAndExecuteCronTasks() {
    if (isDestroyed) return
    
    val currentTime = System.currentTimeMillis()
    
    for ((taskId, cronTask) in cronTasks.toMap()) {
        if (!cronTask.isActive) continue
        
        try {
            if (shouldExecuteCronTask(cronTask, currentTime)) {
                Log.d("MainActivity", "Executing cron task: ${cronTask.taskDescription}")
                updateStatusWithAnimation("⏰ Running scheduled task")
                
                withContext(Dispatchers.Main) {
                    speakText("Running scheduled task: ${cronTask.taskDescription}")
                }
                
                // Execute the task
                executeGeneratedCode(cronTask.taskDescription)
                
                // Update last execution time
                cronTasks[taskId] = cronTask.copy(lastExecuted = currentTime)
                saveCronTasks()
                
                Log.d("MainActivity", "Cron task completed: ${cronTask.taskDescription}")
            }
        } catch (e: Exception) {
            Log.e("MainActivity", "Error executing cron task $taskId: ${e.message}")
        }
    }
}

Cron Expression Format

PhoneClaw uses a simplified cron format:

[second] [minute] [hour] [day] [month]

Supported Patterns

Every N seconds

*/30 * * * *    # Every 30 seconds
*/10 * * * *    # Every 10 seconds

Every N minutes

0 */5 * * *     # Every 5 minutes
0 */15 * * *    # Every 15 minutes
0 */30 * * *    # Every 30 minutes

Every N hours

0 0 */2 * *     # Every 2 hours
0 0 */6 * *     # Every 6 hours

Once daily

0 0 0 * *       # Midnight every day
0 0 9 * *       # 9 AM every day
0 0 18 * *      # 6 PM every day

Expression Parser

From MainActivity.kt:3556-3620:

private fun shouldExecuteCronTask(cronTask: CronTask, currentTime: Long): Boolean {
    val interval = getIntervalFromCron(cronTask.cronExpression) ?: return false
    
    if (cronTask.lastExecuted == 0L) {
        return true  // Never executed, run now
    }
    
    val timeSinceLastRun = currentTime - cronTask.lastExecuted
    return timeSinceLastRun >= interval
}

private fun getIntervalFromCron(cronExpression: String): Long? {
    try {
        val parts = cronExpression.split(" ")
        if (parts.size != 5) return null
        
        val (secondPart, minutePart, hourPart, dayPart, monthPart) = parts
        
        return when {
            // Every N seconds: */30 * * * *
            secondPart.startsWith("*/") -> {
                val interval = secondPart.substring(2).toIntOrNull()
                interval?.let { it * 1000L }
            }
            
            // Every N minutes: 0 */5 * * *
            secondPart == "0" && minutePart.startsWith("*/") -> {
                val interval = minutePart.substring(2).toIntOrNull()
                interval?.let { it * 60 * 1000L }
            }
            
            // Every N hours: 0 0 */2 * *
            secondPart == "0" && minutePart == "0" && hourPart.startsWith("*/") -> {
                val interval = hourPart.substring(2).toIntOrNull()
                interval?.let { it * 60 * 60 * 1000L }
            }
            
            // Daily: 0 0 0 * *
            secondPart == "0" && minutePart == "0" && hourPart != "*" && dayPart == "*" -> {
                24 * 60 * 60 * 1000L
            }
            
            else -> null
        }
    } catch (e: Exception) {
        return null
    }
}

The parser converts cron expressions to millisecond intervals. More complex expressions (specific days, months) are not currently supported.

Creating Scheduled Tasks

Via JavaScript API

// Schedule a task to run every 5 minutes
schedule(
    "magicClicker('refresh button')",
    "0 */5 * * *"
);

// Schedule daily Instagram post at 9 AM
schedule(
    `launchInstagram();
     delay(3000);
     magicClicker('create post');
     // ... rest of upload sequence
    `,
    "0 0 9 * *"
);

// Clear all scheduled tasks
clearSchedule();

Via Kotlin API

From MainActivity.kt:3622-3633:

private fun addCronTask(taskDescription: String, cronExpression: String): String {
    val taskId = UUID.randomUUID().toString()
    val cronTask = CronTask(taskId, taskDescription, cronExpression)
    
    cronTasks[taskId] = cronTask
    saveCronTasks()
    
    val interval = getIntervalFromCron(cronExpression)
    Log.d("MainActivity", "Added cron task: $taskDescription with expression: $cronExpression, interval: ${interval}ms")
    
    return taskId
}

Via AndroidJSInterface

From MainActivity.kt:5480-5530:

@JavascriptInterface
fun schedule(task: String, cronExpression: String) {
    try {
        val taskId = [e-mail](task, cronExpression)
        
        val interval = [e-mail](cronExpression)
        val intervalText = when {
            interval == null -> "unknown interval"
            interval < 60000 -> "${interval / 1000} seconds"
            interval < 3600000 -> "${interval / 60000} minutes"
            interval < 86400000 -> "${interval / 3600000} hours"
            else -> "${interval / 86400000} days"
        }
        
        [e-mail]("Scheduled task to run every $intervalText")
        
        Log.d("AndroidJSInterface", "Scheduled task: $task")
        Log.d("AndroidJSInterface", "Cron expression: $cronExpression")
        Log.d("AndroidJSInterface", "Interval: $intervalText")
        Log.d("AndroidJSInterface", "Total active cron tasks: ${[e-mail]}")
    } catch (e: Exception) {
        Log.e("AndroidJSInterface", "Error scheduling task: ${e.message}")
        [e-mail]("Error scheduling task")
    }
}

@JavascriptInterface
fun clearSchedule() {
    val taskCount = [e-mail]
    [e-mail]()
    [e-mail]()
    [e-mail]("Cleared $taskCount scheduled tasks")
    Log.d("AndroidJSInterface", "Cleared all scheduled tasks")
}

Persistence

Tasks are saved to SharedPreferences as JSON:

Saving Tasks

private fun saveCronTasks() {
    try {
        val jsonObject = JSONObject()
        for ((key, task) in cronTasks) {
            val taskJson = JSONObject().apply {
                put("id", task.id)
                put("taskDescription", task.taskDescription)
                put("cronExpression", task.cronExpression)
                put("createdAt", task.createdAt)
                put("lastExecuted", task.lastExecuted)
                put("isActive", task.isActive)
            }
            jsonObject.put(key, taskJson)
        }
        sharedPreferences.edit().putString("cron_tasks", jsonObject.toString()).apply()
    } catch (e: Exception) {
        Log.e("MainActivity", "Error saving cron tasks: ${e.message}")
    }
}

Loading Tasks

private fun loadCronTasks() {
    try {
        val tasksJson = sharedPreferences.getString("cron_tasks", "") ?: ""
        if (tasksJson.isNotEmpty()) {
            val jsonObject = JSONObject(tasksJson)
            
            val keys = jsonObject.keys()
            while (keys.hasNext()) {
                val key = keys.next()
                val taskJson = jsonObject.getJSONObject(key)
                val task = CronTask(
                    id = taskJson.getString("id"),
                    taskDescription = taskJson.getString("taskDescription"),
                    cronExpression = taskJson.getString("cronExpression"),
                    createdAt = taskJson.optLong("createdAt", System.currentTimeMillis()),
                    lastExecuted = taskJson.optLong("lastExecuted", 0L),
                    isActive = taskJson.optBoolean("isActive", true)
                )
                
                cronTasks[task.id] = task
            }
            
            Log.d("MainActivity", "Loaded ${cronTasks.size} cron tasks")
        }
    } catch (e: Exception) {
        Log.e("MainActivity", "Error loading cron tasks: ${e.message}")
    }
}

UI Integration

PhoneClaw includes a modern UI for managing scheduled tasks:

Task List Fragment

class ScheduledTasksFragment : Fragment() {
    private lateinit var tasksRecyclerView: RecyclerView
    private lateinit var swipeRefresh: SwipeRefreshLayout
    private lateinit var tasksAdapter: TasksAdapter
    
    fun updateTasks(tasks: List<CronTask>) {
        if (::tasksAdapter.isInitialized) {
            tasksAdapter.updateTasks(tasks)
        }
    }
}

Task Management

fun runTaskNow(task: CronTask) {
    mainScope.launch {
        try {
            updateStatusWithAnimation("▶️ Running task immediately")
            speakText("Running task: ${task.taskDescription.take(50)}")
            
            executeGeneratedCode(task.taskDescription)
            
            cronTasks[task.id] = task.copy(lastExecuted = System.currentTimeMillis())
            saveCronTasks()
            updateUI()
            
            speakText("Task completed successfully")
        } catch (e: Exception) {
            Log.e("MainActivity", "Error running task now: ${e.message}")
            speakText("Error running task")
        }
    }
}

fun deleteTask(task: CronTask) {
    MaterialAlertDialogBuilder(this)
        .setTitle("Delete Task?")
        .setMessage("Are you sure you want to delete this scheduled task?")
        .setPositiveButton("Delete") { _, _ ->
            cronTasks.remove(task.id)
            saveCronTasks()
            updateUI()
            speakText("Task deleted")
        }
        .setNegativeButton("Cancel", null)
        .show()
}

Example Use Cases

Daily Social Media Posting

// Schedule TikTok upload every day at 6 PM
schedule(`
    launchTikTok();
    delay(5000);
    
    clickVideoUploadButton();
    delay(2000);
    
    clickFirstGalleryItem();
    delay(3000);
    
    magicClicker('next button');
    delay(2000);
    
    simulateTypeInFirstEditableField('#automation #dailypost');
    delay(2000);
    
    magicClicker('post button');
    speakText('Daily TikTok post scheduled!');
`, "0 0 18 * *");

Periodic Data Scraping

// Check follower count every hour
schedule(`
    launchInstagram();
    delay(3000);
    
    magicClicker('profile tab');
    delay(2000);
    
    const followers = magicScraper('follower count');
    const timestamp = new Date().toLocaleString();
    
    speakText('Current followers: ' + followers);
    
    // Log to Firebase or local storage
    Android.logInfo('FollowerTracking', timestamp + ': ' + followers);
`, "0 0 * * *");

System Monitoring

// Check battery level every 15 minutes
schedule(`
    const battery = magicScraper('battery percentage');
    const batteryNum = parseInt(battery);
    
    if (batteryNum < 20) {
        speakText('Warning: Battery low at ' + battery + ' percent');
        
        // Enable battery saver
        Android.openBatterySettings();
    }
`, "0 */15 * * *");

Automated Engagement

// Like posts every 30 minutes
schedule(`
    launchInstagram();
    delay(3000);
    
    // Scroll through feed
    for (let i = 0; i < 5; i++) {
        magicClicker('like button');
        delay(2000);
        
        swipeUp();
        delay(3000);
    }
    
    speakText('Engagement round completed');
`, "0 */30 * * *");

Best Practices

Rate Limiting: Be mindful of API rate limits and app usage policies. Excessive automation may trigger spam detection on social platforms.

Battery Optimization: Android may kill background processes to save battery. Consider:

• Disabling battery optimization for PhoneClaw
• Using longer intervals (hourly vs. every minute)
• Scheduling during device charging times

Error Recovery

function robustScheduledTask() {
    try {
        // Main task logic
        launchInstagram();
        delay(3000);
        
        if (!isTextPresentOnScreen("Home")) {
            throw new Error("Instagram not loaded");
        }
        
        magicClicker("create post");
        // ... rest of automation
        
    } catch (error) {
        speakText("Task failed: " + error.message);
        Android.logInfo("ScheduledTaskError", error.message);
        
        // Attempt recovery
        speakText("Will retry next scheduled run");
    }
}

schedule(robustScheduledTask.toString(), "0 0 */6 * *");

Troubleshooting

Tasks Not Running

private fun testCronScheduler() {
    mainScope.launch {
        delay(5000)
        Log.d("MainActivity", "Testing cron scheduler...")
        Log.d("MainActivity", "Current tasks: ${cronTasks.size}")
        
        cronTasks.values.forEach { task ->
            Log.d("MainActivity", "Task: ${task.taskDescription}")
            Log.d("MainActivity", "Expression: ${task.cronExpression}")
            Log.d("MainActivity", "Last executed: ${task.lastExecuted}")
            Log.d("MainActivity", "Active: ${task.isActive}")
            
            val interval = getIntervalFromCron(task.cronExpression)
            Log.d("MainActivity", "Calculated interval: ${interval}ms")
            
            val shouldExecute = shouldExecuteCronTask(task, System.currentTimeMillis())
            Log.d("MainActivity", "Should execute now: $shouldExecute")
        }
    }
}

Check Scheduler Status

// Log current scheduled tasks
Android.logInfo("Scheduler", "Checking task status...");

// Verify scheduler is running
if (!isTextPresentOnScreen("Scheduled Tasks")) {
    speakText("Navigate to Scheduled Tasks tab to view active tasks");
}

Performance Considerations

• 60-second check interval provides minute-level precision
• Coroutine-based for lightweight background execution
• Persisted to SharedPreferences for survival across app restarts
• Automatic cleanup when app is destroyed

Lifecycle Management

override fun onDestroy() {
    isDestroyed = true
    
    // Cancel cron checker
    cronCheckJob?.cancel()
    
    // Shutdown executor
    cronScheduler.shutdownNow()
    cronScheduler.awaitTermination(1, TimeUnit.SECONDS)
    
    super.onDestroy()
}

Next Steps

ClawScript API

Full JavaScript automation reference

Vision Targeting

Use vision AI in scheduled tasks