AIClaw’s Built-In Scheduler: Run Agent Prompts and Shell Commands on Cron

AI agents are useful when they can do work on demand. They become much more practical when they can also do that work on a schedule.

AIClaw includes a built-in cron tool and Scheduler page for exactly that. Instead of depending on system crontab glue or an external workflow service, AIClaw runs scheduled jobs inside the same runtime that already knows about your agents, tools, workspace, and execution logs.

Project: https://github.com/chowyu12/aiclaw

The problem with bolting cron onto agents

A lot of agent setups can answer a prompt right now, but recurring work is usually handled outside the agent runtime:

• a system crontab entry;
• a CI workflow;
• a separate automation server;
• or a custom script that calls the agent through another interface.

That works, but it breaks the operating model. The schedule lives in one place, the agent runtime lives in another, and the execution trail is often incomplete.

AIClaw takes a different approach. The scheduler is part of the product runtime, so scheduled work can be created, persisted, executed, and inspected without leaving the platform.

What AIClaw actually ships

From the current repository:

• AIClaw exposes a built-in cron tool for agents.
• Jobs can be prompt jobs or command jobs.
• The scheduler runs in-process using robfig/cron with seconds enabled.
• Jobs are persisted under scheduler/jobs.json.
• Per-job execution logs are appended as JSONL files under scheduler/logs/{id}.jsonl.
• Jobs support enable/disable control, run counts, and optional max_runs.
• The web console includes a Scheduler page where you can inspect jobs and view recent logs.

This is not “LLM asks cron to call a webhook later.” It is part of the same local runtime.

Two job types: agent prompt or shell command

The built-in tool definition exposes two execution modes:

• prompt: send a scheduled prompt back into an AIClaw agent;
• command: execute a shell command.

That split matters in practice.

Use prompt when the recurring work should go through the full agent loop: prompt, tools, plan state, memory, files, and final response.

Use command when you already know the exact shell operation you want to run and do not need model reasoning for that step.

Cron syntax that is useful in real operations

AIClaw’s scheduler accepts:

• 6-field cron expressions with seconds;
• descriptors such as @daily and @hourly;
• interval expressions such as @every 30m.

Examples from the tool definition:

0 0 9 * * *      -> daily at 9:00 AM
0 */5 * * * *    -> every 5 minutes
@every 30m       -> every 30 minutes
@daily           -> once a day at midnight

That makes it usable for both product-style reminders and more operational polling loops.

Why the in-process design matters

The key design choice is that scheduled jobs execute inside AIClaw itself.

For prompt jobs, the scheduler can call the agent executor directly. For command jobs, it can run shell work directly. Because both paths stay inside the product runtime, AIClaw can keep a consistent operational surface:

• one place to define the work;
• one place to inspect the job;
• one place to review success or failure;
• one place to see output and error text.

The design doc in this repo explicitly calls out why this replaced a more traditional crontab-based approach: system cron is Unix-specific and cannot directly drive the agent execution engine.

Persistence and restart behavior

This is one of the most practical parts of the implementation.

When the scheduler starts, it loads persisted jobs from disk and re-schedules enabled entries. That means scheduled work survives process restarts instead of disappearing with the current session.

The job record tracks fields such as:

• expression
• type
• agent_uuid
• prompt
• command
• enabled
• max_runs
• run_count
• last_run_at
• next_run_at

For recurring production use, this is much more useful than “fire and forget.”

Inspectable run logs instead of invisible background work

Each execution produces a structured run record with:

• run time;
• duration;
• status;
• output;
• error.

AIClaw stores those records as JSONL and exposes them through the Scheduler UI and scheduler API routes. The web console can load recent logs for a job, reverse them for readability, and show output or failure text inline.

That gives you a real audit trail for recurring work. If a daily prompt stopped doing what you expected, you can inspect the logs instead of guessing whether the scheduler even fired.

There is also a small but important operational safeguard: per-job log files rotate after a size threshold instead of growing forever.

max_runs is a good fit for temporary automations

Not every schedule should be permanent.

AIClaw jobs can optionally define max_runs. Once the run count reaches that limit, the job disables itself automatically.

This is a strong fit for practical workflows like:

• “run this migration check 10 times while we watch rollout health”;
• “summarize this project standup every workday for two weeks”;
• “poll a dependency update status until the cutover is done.”

You do not need a second cleanup task to stop the first one.

How this fits the rest of AIClaw

The scheduler makes more sense when you look at the rest of the product:

• AIClaw already has a tool runtime.
• It already has agents with configurable prompts and models.
• It already persists conversations, execution steps, generated files, memory, and plan state.
• It already has a web console for inspection.

So a built-in scheduler is not an unrelated extra. It extends the same operating model into recurring work.

Practical examples

Here are a few concrete patterns this enables:

• Daily research brief: schedule a prompt job that asks an agent to gather updates and produce a short report.
• Workspace hygiene: schedule a command job to collect disk usage, rotate artifacts, or run a repo maintenance command.
• Release watch: schedule a prompt job that checks a dependency or upstream project and writes back a structured summary.
• Inbox triage or channel follow-up: schedule an agent workflow at fixed times instead of manually triggering it.

The important part is not just that these jobs run. It is that they run inside the same local-first system where the rest of the agent work already happens.

Why I think this feature is worth highlighting

Many AI agent demos stop at interactive chat. AIClaw treats agent execution more like an operating system concern: prompts, tools, plans, memory, files, logs, and now scheduled recurrence all belong to the same runtime.

That makes the scheduler a meaningful feature even without a brand-new release attached to it. It shows how AIClaw is designed for repeatable work, not just one-off conversations.

If you are building local-first agents and want recurring jobs without handing control to an external automation platform, this part of AIClaw is worth a look.

Install or update:

curl -fsSL https://raw.githubusercontent.com/chowyu12/aiclaw/master/install.sh | bash

GitHub: https://github.com/chowyu12/aiclaw