Docs
Run an AI agent on a schedule
Give a job a cron line and it runs on its own, in your timezone, with every run written down and no two runs overlapping.
A scheduled agent is a job with a cron line. npx chloe keeps every cron line
of every agent, so there is no separate scheduler to set up.
A job on a timer
every from @chloejs/core/timer writes the cron line in words, and
timezone is a real timezone name, so daylight saving is handled. Without one,
the line is read in UTC. This job checks the orders every two hours and asks no
model, so it costs nothing:
export default defineJob({
id: "stuck-orders",
cron: every(2).hours,
timezone: "America/New_York",
description: "The warehouse knows about every order that is paid for and late.",
run: async (work) => {
const all = await work.step("read the orders", () => orders());
const late = all.filter((one) => stuck(one));
if (late.length === 0) return { checked: all.length, late: [], worth: 0 };
const worth = late.reduce((total, one) => total + one.total, 0);
await work.step("tell the warehouse", () =>
tellTheWarehouse(
`${late.length} paid order${late.length === 1 ? "" : "s"} past the promised date`,
late.map((one) => `${one.id}: promised ${one.promised.slice(0, 10)}, ${money(one.total)}, ${one.lines.length} line(s)`),
),
);
return { checked: all.length, late: late.map((one) => one.id), worth };
},
response: (r) =>
r.late.length === 0
? `${r.checked} orders, none late`
: `${r.late.length} late, ${money(r.worth)} sitting: ${r.late.join(", ")}`,
});This one sorts the inbox every 15 minutes with one model call per run, however many messages came in:
export default defineJob({
id: "sort-messages",
cron: every(15).minutes,
timezone: "America/New_York",
description: "Every message a customer wrote in is on the right desk.",
model: "anthropic/claude-haiku-4.5",
run: async (work) => {
const waiting = await work.step("read what came in", () => unread());
if (waiting.length === 0) return { sorted: 0, urgent: [], desks: {} as Record<string, number> };
const read = await work.model("work out what each one is about", {
instructions:
"You sort a shop's inbox. Judge only what the customer wants, not what should be done about it. " +
"Every message gets exactly one line back, with the id copied exactly.",
output: Sorted,
prompt: waiting.map((one) => `${one.id} (${one.at}): ${one.text}`).join("\n\n"),
});
// The rules, in code: where each one goes, and which are worth interrupting
// somebody for. The model never decides either.
const desks: Record<string, number> = {};
for (const desk of new Set(read.sorted.map((one) => DESK[one.about]))) {
const ids = read.sorted.filter((one) => DESK[one.about] === desk).map((one) => one.id);
desks[desk] = await work.step(`hand ${ids.length} to ${desk}`, () => handTo(desk, ids));
}
const urgent = read.sorted.filter((one) => one.urgency === "today" || one.wantsMoneyBack);
return { sorted: read.sorted.length, urgent: urgent.map((one) => `${one.id}: ${one.inAWord}`), desks };
},
response: (r) =>
r.sorted === 0
? "nothing came in"
: `${r.sorted} sorted into ${Object.keys(r.desks).length} desk(s)` +
(r.urgent.length ? `, ${r.urgent.length} for today: ${r.urgent.join("; ")}` : ""),
});A prompt on a timer
A job can be only words. This one runs every Sunday evening and decides for itself whether there is anything to say:
// The one job here that is a prompt from end to end.
//
// The words are in how-it-went.md beside this file. It is a prompt rather than
// code because what to make of a week of runs is not a rule anybody could write
// down, and because it decides for itself whether there is anything to say.
import { defineJob, prompt } from "@chloejs/core";
import { every } from "@chloejs/core/timer";
export default defineJob({
id: "how-it-went",
cron: every.sunday.at("18:00"),
timezone: "America/New_York",
description: "You know whether anything about the shop has been quietly getting worse.",
markdown: prompt("jobs/how-it-went.md"),
});What a schedule promises
- No overlap. A second run of the same job is skipped, not queued.
- No silent mistakes. A cron line that cannot run evenly, like every 7 minutes, is refused when the file loads, with the reason.
- No lost waits. A job waiting on a person survives a restart.
- A record. Every run writes down each step and what it cost.
Every form every takes is in A job is a workflow.
Keep it running
Nothing fires unless npx chloe is running. npx chloe install makes it a
service, a systemd user unit on Linux or a launchd agent on a Mac, so it keeps
going after you close the terminal and after a reboot.