Scheduled Tasks

Elftia's scheduled task system (Cron) lets you automatically execute repetitive work on a schedule. It supports two action types — desktop notification reminders and AI Agent task execution — and can push results to Channel messaging platforms.

Use Cases

• Have AI summarize the latest tech news every morning at 9 AM
• Check an API's status every 30 minutes and notify you
• Send a one-time reminder at a specified time
• Periodically have an AI Agent run data analysis and push the results to Discord or Telegram
• Automatically generate the week's work plan every Monday morning

Creating a Scheduled Task

Steps

1. Open the Cron management page (from the sidebar or navigation menu)
2. Click the Create Task button
3. Fill in the task information:
   • Task name — give the task a descriptive name
   • Description (optional) — describe the task's purpose in detail
   • Schedule type — select the execution frequency (see schedule types below)
   • Action type — choose notification or Agent execution
   • Message content — the notification text or Agent prompt
4. (Optional) Configure Channel push
5. (Optional) Select the LLM provider and model for Agent tasks
6. Click Save

Schedule Types

Elftia supports three scheduling methods covering everything from simple to complex timing needs.

Cron Expression

Use a standard 5-field cron expression for precise control over execution time.

Format: minute hour day month weekday

Field	Range	Special Characters
Minute	0-59	* , - /
Hour	0-23	* , - /
Day	1-31	* , - /
Month	1-12	* , - /
Weekday	0-7 (0 and 7 are both Sunday)	* , - /

Common examples:

Expression	Meaning
0 9 * * *	Every day at 9:00 AM
30 8 * * 1-5	Weekdays at 8:30 AM
0 */2 * * *	Every 2 hours on the hour
0 9 1 * *	The 1st of every month at 9:00 AM
0 9 * * 1	Every Monday at 9:00 AM
*/15 * * * *	Every 15 minutes
0 9,18 * * *	Every day at 9:00 AM and 6:00 PM

Special character reference:

Character	Description	Example
*	Matches all values	* * * * * every minute
,	Lists multiple values	0,30 * * * * at 0 and 30 minutes past every hour
-	Range	0 9-17 * * * on the hour from 9 AM to 5 PM
/	Step	*/10 * * * * every 10 minutes

:::tip Visual Assistance When creating a task, the interface provides a visual schedule mode selector with presets such as daily, weekdays, weekly, monthly, and hourly — no need to write a cron expression by hand. Selecting a preset automatically generates the corresponding cron expression. :::

Interval Execution (every)

Repeat the task at a fixed interval.

Format: number + unit

Unit	Symbol	Example
Seconds	s	30s — every 30 seconds
Minutes	m	5m — every 5 minutes
Hours	h	1h — every 1 hour
Days	d	3d — every 3 days

Behavior notes:

• The interval is calculated from the time the previous execution completed
• After the app restarts, the system resumes timing from the last recorded execution time and does not trigger immediately

One-time Execution (at)

Execute the task once at a specified exact time; automatically disabled after execution.

Format: ISO 8601 datetime string

Example: 2026-04-15T09:00:00

Behavior notes:

• The task fires in the next check cycle after the specified time is reached (the check interval is 30 seconds)
• After execution completes, the task automatically switches to disabled state
• Expired one-time tasks are not triggered

Action Types

Notification (notify)

Send a desktop system notification.

• When the task fires, a desktop notification pops up displaying the task name and message content
• Requires the system to allow the app to send notifications
• Can be enabled or disabled in Elftia's notification settings

Agent Execution (agent)

Trigger an AI Agent to execute a specified prompt task.

• When the task fires, the system sends the message content as a prompt to the AI Agent
• The Agent executes the instructions in the prompt and generates a response
• The response is recorded in the execution history (up to the first 2,000 characters are stored)
• If no Channel is configured for the task, the execution result is displayed via a desktop notification (controlled by notifyOnComplete)

Configuring the LLM Provider

Agent tasks can specify the LLM provider and model to use:

Config	Description
Provider (providerId)	Select the LLM provider to run the task
Model (model)	Select the specific AI model

If not specified, the current default provider and model are used.

Channel Push

Scheduled tasks support pushing execution results to external messaging platforms (such as Discord, Telegram, etc.).

Configuration Steps

1. When creating or editing a task, enable Channel Push
2. Select the target Channel (must first be configured in Channel management)
3. Enter the target Chat ID (the group or channel ID within the Channel)
4. After the Agent finishes execution, results are automatically sent to the specified Channel

Behavior Notes

• For Agent tasks configured with a Channel, the prompt includes Channel information
• The Agent is instructed to use the channel_send MCP tool to send results to the target Channel
• Agent tasks without a Channel configured execute locally only, with results shown via desktop notification

Execution History

Each task's execution history is automatically recorded. A maximum of 200 recent records are retained per task.

History Record Fields

Field	Description
Timestamp	When the execution started
Status	ok (success) or error (failure)
Duration	Execution time (milliseconds)
Error message	Error description if failed
Agent response	The Agent task's reply content (up to 2,000 characters)

Viewing History

1. Click a task on the Cron management page
2. Expand the task detail panel
3. View the Execution History tab

Task Management

Pause / Resume

• Click the task's toggle switch to pause or resume the task
• A paused task is not triggered until it is re-enabled

Run Now

• Click the task's Run Now button to manually trigger one execution
• Does not affect the task's normal schedule
• If the task is already running, clicking again does not create a concurrent execution

Edit

• Click a task to enter edit mode
• You can modify the name, description, schedule type, action type, and Channel configuration
• The next execution time is automatically recalculated after saving changes

Delete

• Deleting a task also clears its execution history records
• Deletion cannot be undone

Status Event Broadcasting

Scheduled tasks broadcast status events to the frontend during execution:

Status	Description
running	Task started
success	Task completed successfully
error	Task failed

The interface updates the task status indicator in real time so you can see the status of background tasks at a glance.

System Behavior

Behavior	Description
Poll interval	Reload task configuration every 5 seconds
Check interval	Check schedule times every 30 seconds
Cron deduplication	The same cron task fires only once within the same minute
Concurrency control	The same task does not execute concurrently
Data storage	Task configs are stored in jobs.json; history records are stored in the runs/ directory

FAQ

Problem	Solution
Task did not execute on time	Confirm the task is enabled and the schedule expression is correct
Cron expression is invalid	Use the visual schedule mode in the interface, or refer to the expression examples above
Agent task execution failed	Check that the LLM provider is configured correctly and the API Key is valid
Channel push message not received	Confirm the Channel is correctly configured and the Chat ID is valid
One-time task was not triggered	Confirm the specified time has not yet passed; the time must be in ISO format
History records are truncated	The system automatically retains the most recent 200 records; older records are cleared
Interval task triggers immediately after app restart	Under normal circumstances it does not trigger immediately; the system resumes timing from the last execution time

Related Links

• Agent — learn about the Agent system; Agents are the execution engine for scheduled tasks
• Channel — configure message push channels
• Chat — use AI features in conversations