Cron jobs (scheduling work to run on its own)
The Cron Jobs screen: how to create and manage a scheduled job by hand — the three job types (Script, Recipe, Session) and the fields each one takes, the schedule, approval and self-healing switches, the jobs dashboard with its search and grouping, per-job run history, and Run Now. The companion page covers handing a job's description to an AI to create. Also covers fire-time timing (a start can be up to ~2 minutes late under load) and the six alerts it can raise. A wake schedule explicitly marked as owner-mandated keeps running when its rounds are quiet. The quiet notices still appear, and the owner or its target session can stop it deliberately. The owner adds this mark from the quiet-wake card's "Keep it on" action when the app asks whether to keep the schedule, or through the owner-only scheduled-job routes; a session cannot set or clear it. Older schedules keep their existing behavior until marked.
On this page
What it is
A cron job is something Omniscio does for you on a timetable — run a command, fire a saved recipe, or start a fresh Claude session — without you being there to press go. The Cron Jobs screen is where you create those jobs, see the ones you have, look at whether they actually ran, and fire one by hand when you do not want to wait for its next turn.
Every run is recorded, so "did the nightly job actually happen?" has an answer rather than a guess.
Where to find it
- The Cron Jobs screen is a virtual project in the sidebar, headed Scheduled Tasks (Cron). It lists your jobs; + Add Job creates one, and there is a Search jobs… box.
- Grouping and filtering sit above the list: group By <project> or By Frequency, and a Show completed checkbox to include the jobs that are finished rather than active.
- A job is one row. Clicking it opens its detail view — the settings, its run history, and Run Now. The row itself also carries Run Now (hover it: "Run this job once right now."), which asks you to confirm first.
- The row's actions menu (the ⋯ button) carries Edit, Run Now, Enable / Disable and Delete. Delete asks you to confirm first: the job and its run history are removed, and that cannot be undone.
- Creating or editing a job opens a New Cron Job / Edit Cron Job dialog, described below.
- On a phone the screen fits the narrow width: the Scheduled Tasks (Cron) heading stays at the top with the number of jobs under it, search is a magnifier button beside the heading (tap it to open a full-width search box, tap again to close and clear it), and the grouping toggle sits on its own row with + Add Job. Each row shows the job's status next to its schedule and keeps the row's ⋯ menu at the end of that same line, so long job names get the whole width and wrap to at most two lines.
How it behaves
Creating a job
The dialog is a set of cards, top to bottom.
- Name and Description — the name is what you will see in the list, so make it say what the job does.
- Job Type — one of three, and the choice changes the rest of the form:
- Script — run a shell command. You give it a Command and a Working Directory, and there is a Run in a visible window option for commands that need to show you something (most should stay hidden).
- Recipe — run one of your saved recipes, chosen with a recipe picker. Use this when the work is already a multi-step workflow you maintain elsewhere.
- Session — start a new Claude session with a prompt you write, optionally giving the session a fixed Session Name, and optionally setting a specific AI engine for it. This is the type to use when the scheduled work needs judgement rather than a fixed command.
- Project — which project the job belongs to.
- Visibility — whether a job that starts a session is silent, visible, or follows the recipe's own default. Silent sessions stay out of your attention path.
- Schedule — when it fires.
- Require Approval — when on, every run lands in your inbox as an approval before it happens. Use it for anything that costs money or touches something you would not want running unattended. A job waiting on that approval keeps asking: if you clear its card without approving it, the card comes back within a few hours while the job is still paused, so a schedule can never sit switched off because its one notice was dismissed.
- Self-Healing — whether a job that fails for good is handed to a fresh session to diagnose and fix; see Cron self-healing.
- Run if missed — whether a fire that was missed while the app was closed runs late.
- Environment Variables — extra variables for this job's runs only, stored encrypted.
Editing a job
Editing an existing job opens the same dialog with what is already there filled in. Your changes are saved on top of the job's existing settings rather than replacing them, so anything the dialog does not show you is left exactly as it was.
That matters most for a check-in — a schedule whose job is to wake a session you already have, rather than start a new one. Renaming it, changing its time, or re-wording its prompt all leave it aimed at the same session, so it carries on waking that session instead of quietly turning into a schedule that starts (and bills) a brand-new session every time it fires.
An edit also leaves a check-in the app stood down switched off. Re-arming one is its own deliberate action, never a side effect of an unrelated edit.
Running a job after another one finishes
A job can be made to follow another instead of running on its own clock. In the editor this is the Run After card: Trigger After Job picks the job to follow — the card says plainly, "Run this job after another job completes." — and Trigger Condition decides when that counts.
Three conditions are offered, and the difference between the last two matters:
- Success — fire only if the job it follows finished successfully. This is the default.
- Failure — fire only if it failed. The usual use is a cleanup or a notification that should happen exactly when the main job breaks.
- Always — fire whichever way it ended, success or failure.
Whichever you pick, it is judged on the job's final result: a job that retries is allowed to finish retrying first, so a chain never fires on a failure the job then recovered from.
The one thing to know before you chain two jobs together: nothing stops a loop. There is no limit on how deep a chain may go and no check that a chain has come back around to a job it already ran, so if you set A to follow B and B to follow A, the pair will keep firing each other for as long as both are enabled. Chaining is a plain "follow this one" link, not a guarded graph — so when you build a chain, satisfy yourself that it ends somewhere, and use the job's own enable/disable toggle to stop one if it does not.
Running a job when an alert appears
Instead of a clock, a job can run each time a chosen alert appears. In the editor's Schedule card, Run When an Alert Is Raised lists every alert type by name; pick one and the clock picker steps aside. The job list then shows "When this alert appears: …" in place of a schedule. Pick No — run on the schedule below to go back to a clock.
- It runs once for each new alert of that type. A card that is merely refreshed in place does not run it again, and a job runs at most once every 10 minutes however many alerts arrive.
- Only alerts Omniscio itself raises start a job — never one an agent raised — so nobody can fake an alert to run your script.
- The job gets the alert's id, type, title and text (
AMC_ALERT_ID,AMC_ALERT_KEY,AMC_ALERT_TITLE,AMC_ALERT_TEXT). A one-line command cannot paste those in — the save is refused, because the alert text would become part of the command. Read them inside a script instead. - Like any job an AI sets up, it waits for your approval before it can ever run, and changing which alert it follows asks again. If you mute an alert type, it is never raised, so it starts nothing.
The everyday use: have an agent write a two-line script — "text me" or "post this to Slack" — and hook it to the alert you care about, such as DeepSeek runs out in under 2 hours.
Watching what a job did
Each job keeps a run history — one entry per firing, so you can see whether it ran, when, and how it ended, without reading logs. The list refreshes when a run of the open job starts as well as when it finishes, and it keeps however many earlier runs you had already loaded instead of jumping back to the newest few. Beside it, Run Now fires the job immediately; it asks you to confirm first, because a job that spawns a session or sends something is not a free action.
Run history is kept for 30 days and then deleted, permanently. The app sweeps once a day and drops every run record older than that, so a job's history is a rolling month rather than a permanent log — and nothing in the app can bring a purged record back. 30 days is fixed; it is not tied to your data-retention setting and there is no way to raise it, so if you need a durable record of what a job did, have the job write it somewhere yourself rather than relying on the run list. The same 30-day sweep covers the app's other run-audit records — automation runs and their dead letters, the PR merge queue's runs, the PR reconcile ledger, the PR janitor's runs and dispositions, resolved recipe-approval requests, cron heal attempts, workflow-coach runs, and aggregation runs — so "a month" is the honest answer for how far back this class of history goes anywhere in Omniscio.
The jobs Omniscio adds for itself
Some jobs in the list you did not create. Omniscio maintains a handful of housekeeping jobs and seeds them into the same Cron Jobs list, each carrying a description that ends "(auto-managed)" so they are recognisable. They exist so the app can notice its own drift instead of waiting for a person to notice. On a machine where the thing they watch does not apply, they are never seeded at all — so you may have none of these, or several.
plugin-publish-drift-check— every 6 hours. Alerts when a marketplace plugin's repo has finished work that was never published.- Firebase deploy drift is no longer a set of housekeeping jobs. The per-unit
firestore-rules-drift-check/firestore-indexes-drift-check/firebase-functions-drift-checkjobs were retired on 2026-10-07: one disagreement used to arrive as several cards, each ending in a hand-run deploy command. A single scheduled job now owns the whole subject and raises one card with a one-click deploy. The card clears itself once a check reads every deployed unit and finds nothing behind; if part of a check could not reach Google Cloud, the card is left as it is until a full check succeeds. If you upgraded from an older build, the app deletes the old jobs for you on first start; you do not have to remove them yourself. worktree-triage-dispatch— every 30 minutes. Dispatches triage for worktrees whose work was left stranded.
These are ordinary jobs once seeded, so you can inspect, disable, re-schedule or delete any of them like one of your own. Be aware that deleting one is not permanent in the way you might expect: the seeding is idempotent and re-runs on startup, so the app will recreate a housekeeping job it still needs.
A scheduled fire can start late, on purpose
Three rate controls sit between "the schedule came due" and "the job started". All three exist because of one measured failure: a process-creation storm — a wave of sessions and two cron jobs starting processes 12ms apart — was enough to hang the machine. Spacing out starts is the fix, and the cost is that a fire's start time is not exactly its scheduled time.
- A per-job phase offset — up to 45 seconds. Before anything else, each scheduled fire waits an
offset derived from its own job id (the id hashed into a window, default 45 seconds, capped at
59 so a fire stays inside its scheduled minute). This matters most for schedules like
*/5, where several jobs come due on the same tick every five minutes: without the offset they would all begin ramping at once. It is deterministic — a given job always fires at the same second of its minute, so it never drifts and nothing needs to be stored. - A calm wait — up to 90 seconds, only while the machine is busy. If the whole computer is under heavy load (roughly 85% busy), the fire waits in 10-second steps until things calm down, up to a 90-second ceiling. It is a ceiling, not a skip: past it the job proceeds regardless, so a loaded machine delays a run and can never lose one.
- A serialising start throttle — 4 seconds. Two dispatch releases are spaced at least 4 seconds apart, so two due jobs can never start their process trees in the same instant.
What this looks like in practice. On an idle machine a job scheduled for 09:00 starts within its 09:00 minute, as you would expect (the phase offset is deliberately bounded to keep it there). On a loaded machine it can be pushed past the minute — a 45-second offset plus a 90-second calm wait is the worst case, so if you are comparing a log timestamp against your schedule, a start up to about two minutes late is normal behaviour under load, not a fault. If you need to know whether the scheduler is healthy rather than merely slow, the alerts below are the signal to read.
A manual Run now is never delayed
Run now dispatches the job directly rather than through the scheduled path, so none of the three controls above apply to it. It is never held behind a phase offset or a calm window.
Alerts the scheduler can raise
Six alerts are raised by the scheduler's own alert builders (cron-engine-alerts.ts), on top of the
job-failure alert that has a page of its own (cron failure alerts) — so
seven conditions can land in your inbox from cron, and every one of them means something different. A
job that is slow, a job that is broken, and a scheduler that has stopped are three separate problems
with three separate fixes, and before this list five of them had no published explanation at all.
Every one of these is deduped (one row per condition, updated rather than repeated) and every one clears itself when the condition goes away — so an alert disappearing is the all-clear.
| Alert | What it means | What to do |
|---|---|---|
| A scheduled job fails (toast + card) | A run failed, and self-healing is not taking it over. | Its own page: cron failure alerts. |
| A scheduled job keeps timing out | The job starts but never finishes — it has started and been stopped for timing out several times in a row, so it never completes. It is probably waiting on something that never responds. | Open its schedule and review what it waits on, or turn it off. |
| Scheduled jobs have stopped running | The scheduler itself is unhealthy: every recent tick threw. This is the broad one — it means backups, reports and automations may simply not be running. Usually a locked or busy local database. | Restart Omniscio. It normally clears this, and the alert clears itself once the scheduler recovers. |
| A scheduled job has stopped running (overdue) | The scheduled time passed and the job never ran, and its schedule has fallen behind. The job may be stuck, or the scheduler may need a restart. | Open its schedule to review or turn it off. Clears when the job runs again. |
| A scheduled job keeps failing to start | The job has failed to start on several recent checks — it is not running at all. Usually a bad setting: an environment variable that no longer resolves, or a project that no longer exists. A job that does start and then fails is not this card; its run is recorded as failed and gets the ordinary failure notice instead. | Open its schedule and check its settings. Clears on the next successful start, including one you start yourself with Run now, and including after a restart. |
| A scheduled job is paused until restart | The job started, got stuck, and could not be stopped cleanly — so it was paused deliberately, to avoid running a duplicate of work that may already be under way. | It will not run again until you restart Omniscio (or turn it off). Clears once it runs again. |
| Some automation actions could not be completed | An automation's action permanently failed after every retry and was set aside rather than dropped. | See automations and auto-replies. |
Two of these are worth telling apart at a glance, because the fixes are different sizes: "Scheduled jobs have stopped running" is plural and about the scheduler (restart), while "A scheduled job has stopped running" is singular and about one job (inspect it). If several jobs are misbehaving at once, believe the plural one.
Related
- Create a cron job with AI — handing the job description to an AI, and the approval step that follows.
- Cron session jobs — the Session job type in depth: how each run is numbered, the live-session guard, and the five-minute floor.
- Cron self-healing — what happens when a job fails for good.
- Cron run if missed — the catch-up switch.
- Cron failure alerts — how a failing job gets your attention.
- Cron group rename — naming the groups the sidebar sorts jobs into.
- CLI Control — the local server the
/cron/jobsroutes belong to.
Last verified 2026-10-19