Tmux SchedulerInstall

Overview

The node, named "Tmux Scheduler," is designed to schedule and manage various timed tasks within a tmux environment or similar terminal multiplexing context. It supports scheduling agent check-ins, creating reminders, managing cron jobs, listing scheduled tasks, canceling tasks, and batch scheduling multiple tasks at once.

A common use case is automating routine checks or reminders for agents or processes running in tmux sessions, enabling users to set up notifications or commands to run at specific times or intervals. For example, an operations team could schedule periodic status check-ins on different tmux windows or create reminders for maintenance tasks.

The Batch Schedule operation specifically allows users to schedule multiple check-in tasks simultaneously by providing a JSON array of task definitions, each specifying the target window, delay in minutes, and an optional note.

Properties

Example of the expected JSON format for Schedule Tasks:

[
  {
    "targetWindow": "session:0",
    "minutes": 30,
    "note": "Check progress"
  }
]

Output

The output JSON structure for the Batch Schedule operation includes:

• success: Boolean indicating if the batch scheduling process completed without critical failure.
• totalTasks: Total number of tasks provided in the input array.
• successCount: Number of tasks successfully scheduled.
• failureCount: Number of tasks that failed to schedule.
• results: An array containing individual results for each task:
  • On success: Includes success: true, targetWindow, minutes, note (if any), and the ISO timestamp scheduledTime when the check-in will occur.
  • On failure: Includes an error message and the original task object.
• timestamp: ISO string representing when the batch scheduling was performed.

Example output snippet:

{
  "success": true,
  "totalTasks": 2,
  "successCount": 1,
  "failureCount": 1,
  "results": [
    {
      "success": true,
      "targetWindow": "session:0",
      "minutes": 30,
      "note": "Check progress",
      "scheduledTime": "2024-06-01T12:30:00.000Z"
    },
    {
      "error": "Missing required fields: targetWindow and minutes",
      "task": { "minutes": 15 }
    }
  ],
  "timestamp": "2024-06-01T12:00:00.000Z"
}

Dependencies

• Requires access to a tmux environment or compatible terminal multiplexer where scheduled tasks can be executed.
• Optionally uses external scripts if configured via credentials (e.g., a directory for custom scripts).
• Uses system utilities such as at for scheduling one-time tasks and crontab for recurring jobs.
• Reads and writes temporary files (e.g., /tmp/tmux-reminders.json) to store reminders.
• Requires an API key credential for the orchestrator service (referred generically as "an API key credential") which may provide additional scheduling capabilities.

Troubleshooting

• Common Issues:

  • Invalid JSON format in the "Schedule Tasks" property will cause parsing errors.
  • Missing required fields (targetWindow or minutes) in any task object will result in that task failing.
  • Scheduling failures may occur if the underlying system utilities (at, crontab) are not available or properly configured.
  • Permission issues writing to or reading from temporary files like /tmp/tmux-reminders.json.
  • If external scripts are enabled but missing or inaccessible, scheduling may fail with errors about missing scripts.

• Error Messages:

  • "Failed to batch schedule: ..." indicates a problem parsing or processing the batch input.
  • "Missing required fields: targetWindow and minutes" means a task object lacks necessary properties.
  • Errors related to system commands (e.g., at, crontab) usually indicate environment setup problems.
  • "Unable to schedule check-in: send-claude-message.sh script not found" suggests a required helper script is missing.

• Resolutions:

  • Validate JSON input before running the node.
  • Ensure all tasks have the required fields.
  • Verify that system scheduling utilities are installed and accessible.
  • Check file permissions for temporary storage locations.
  • Confirm external scripts directory is correctly configured if used.

Links and References

• tmux official documentation
• Linux at command manual
• Cron job basics
• Node.js child_process.execSync (used internally for system commands)