Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

Automations let you schedule AI prompts to run on a recurring schedule — without any manual trigger. You write a prompt once, set a schedule, and OpenClicky runs it automatically: every hour, every morning at 9 am, every Monday, or on any custom cron schedule. Results appear in the agent panel like any other session, and the response can update memory, write files, or surface in the widget — all without you lifting a finger.

​
What an Automation Is

An OpenClickyAutomation is a persistent record that pairs a prompt with a schedule. The automation store (OpenClickyAutomationStore) runs a 30-second timer tick. On each tick it checks whether any enabled automation’s nextRun timestamp is in the past, and if so fires the prompt as a new agent session. 
// OpenClickyAutomation model fields
struct OpenClickyAutomation: Codable, Identifiable, Equatable {
    var id: UUID
    var name: String
    var schedule: OpenClickyAutomationSchedule
    var prompt: String
    var agentSlug: String?   // nil = default chat session
    var enabled: Bool
    var lastRun: Date?
    var nextRun: Date?
}
Automations are persisted as JSON at: 
~/Library/Application Support/OpenClicky/automations.json

​
Schedule Types

OpenClicky supports two schedule types:

Interval

Fire every N seconds. Specified as a TimeInterval. The store displays these as human-readable strings like every 30m, every 2h, or every 1h 30m.

Cron

A standard 5-field cron expression. Full support for numbers, lists, ranges, steps, and wildcards. The store displays these as cron 0 9 * * 1 etc.

​
Display Strings

The displayString property on OpenClickyAutomationSchedule generates the label shown in the Automations panel:
ScheduleDisplay
.interval(seconds: 1800)every 30m
.interval(seconds: 7200)every 2h
.interval(seconds: 5400)every 1h 30m
.cron("0 9 * * 1")cron 0 9 * * 1

​
Cron Expression Reference

OpenClicky’s built-in CronExpression evaluator parses standard 5-field cron syntax. Fields are evaluated in order: 
┌──────── minute (0–59)
│ ┌────── hour (0–23)
│ │ ┌──── day-of-month (1–31)
│ │ │ ┌── month (1–12 or JAN–DEC)
│ │ │ │ ┌ day-of-week (0–7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

​
Supported Operators

OperatorExampleMeaning
Wildcard ** * * * *Match every value in the field’s range
Number30 9 * * *Match exactly that value
List0 9,17 * * *Match any value in the comma-separated list
Range0 9 1-5 * *Match every value from start to end inclusive
Step*/15 * * * *Match every Nth value across the full range
Step on range0 9-17/2 * * *Match every 2nd hour from 9 to 17

​
Named Values

Month and day-of-week fields accept 3-letter abbreviations (case-insensitive):
  • Months: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
  • Weekdays: SUN, MON, TUE, WED, THU, FRI, SAT
Both 0 and 7 mean Sunday in the day-of-week field, matching the behaviour of standard cron implementations.

​
Computing the Next Run Date

The evaluator starts one minute after the reference date, zeros out seconds, then walks minute-by-minute up to 366 days forward until all five fields match. The result is the next Date the cron expression is satisfied: 
// CronExpression.nextFireDate(after:)
// Walks minute-by-minute checking minutes, hours, days, months, weekdays
while candidate < limit {
    let comps = calendar.dateComponents([.minute,.hour,.day,.month,.weekday], from: candidate)
    if minutes.contains(m), hours.contains(h), days.contains(d),
       months.contains(mo), weekdays.contains(wd) {
        return candidate
    }
    candidate = calendar.date(byAdding: .minute, value: 1, to: candidate) ?? candidate
}

​
Creating an Automation

1

Open the Automations panel

In the OpenClicky notch panel, go to Agents → Automations or open Settings → Automations.
2

Tap the + button

Fill in a name, prompt, and schedule. Toggle Enabled to activate it immediately.
3

(Optional) Assign a specialist agent

Set agentSlug to route the automation to a specific specialist agent. Leave blank to use the default chat session.
4

Save

The store computes nextRun from the current time and the chosen schedule, then persists the automation to automations.json.

​
Routing: Default vs Specialist Agent

When an automation fires, the store checks agentSlug:
  • No slug — the prompt is submitted via CompanionManager.submitAgentPromptFromUI(_:), running in the default chat session.
  • With slug — the store calls createAndSelectNewCodexAgentSession(asAgent:) to launch a fresh session under the named specialist agent, then submits the prompt to that session. The session ID is tracked so the store can detect if the previous run is still active before starting another.
If a previous run of the same automation is still active when the next scheduled tick arrives, the store defers the next run by 60 seconds rather than stacking a second session on top of a still-running one.

​
Example Use Cases

Run every weekday morning at 8 am to summarise overnight emails, calendar events, and top news:
Name:    Morning Digest
Schedule: cron 0 8 * * MON-FRI
Prompt:  Check my calendar for today's events via gog, find the top 5 unread
         emails from overnight, and pull three tech headlines from the web.
         Write a brief morning briefing and save it to memory.md.
Agent:   (default)
Poll a weather API every hour and update a local status file:
Name:    Hourly Weather
Schedule: .interval(seconds: 3600)  →  "every 1h"
Prompt:  Fetch current weather for my location from wttr.in and append a
         one-line summary with temperature and conditions to
         ~/Documents/weather-log.txt.
Agent:   (default)
Generate a weekly summary of git activity and open issues every Monday at 9 am:
Name:    Weekly Project Report
Schedule: cron 0 9 * * MON
Prompt:  Run `git log --oneline --since=1.week` in ~/Projects/myapp,
         list open GitHub issues via the Composio MCP, and write a
         brief weekly report to ~/Documents/reports/week-$(date +%Y-%m-%d).md.
Agent:   (default)
OpenClicky ships a built-in App skill discovery automation (disabled by default). When enabled, it runs every 6 hours and scans for useful skills, MCPs, and integrations that match the apps you’ve been using. Results appear in the Connect tab as install/connect suggestions.
Schedule: .interval(seconds: 21600)  →  "every 6h"
Agent:   skill-discovery (specialist agent)
Enable it in Settings → Automations → App skill discovery.

​
Concurrency and Persistence

The automation scheduler runs a Timer on a 30-second interval on the main run loop. Because the interval is short, automations fire within 30 seconds of their scheduled time rather than exactly on the second. For hour-level or day-level schedules this is imperceptible.
Interval-based automations compute nextRun relative to the previous lastRun (or the current time if it has never run). If OpenClicky is not running when a scheduled time passes, the automation fires as soon as the app launches and the tick notices the missed nextRun is in the past.
All automation state is written atomically to automations.json after each tick mutation. Dates are encoded as ISO 8601 strings.

Build docs developers (and LLMs) love

Get started for freeTalk to us