Schedule AI Tasks with OpenCode Scheduler
OpenCode Scheduler lets you run AI agents on a schedule using your OS native timers — launchd, systemd, or Task Scheduler.
OpenCode has become a popular terminal-based AI coding agent. But what if you want your AI agent to run autonomously — checking deals at 9 AM, summarizing GitHub notifications every Monday, or monitoring your website every 6 hours — without keeping your terminal open?
Enter OpenCode Scheduler: an official OpenCode plugin that turns your OS into a scheduling engine for AI agents.
What is OpenCode Scheduler?#
OpenCode Scheduler is a plugin for the OpenCode ↗ CLI framework that lets you schedule recurring AI agent tasks using your operating system’s native scheduler — launchd on macOS, systemd --user on Linux, schtasks on Windows, with cron fallback where native backends aren’t available.
Instead of running a heavy background daemon or relying on a cloud cron service, the plugin acts as a thin wrapper around battle-tested OS schedulers that already run on your machine.
Key Features#
Natural Language Scheduling#
You describe what you want in plain English. The plugin translates it into the right cron expression and OS scheduler configuration.
“Schedule a daily job at 9am to search Facebook Marketplace for standing desks under $300 and send the top 5 deals to my Telegram”
No need to memorize cron syntax — though if you know it, the plugin accepts standard 5-field cron expressions too.
OS-Native Execution#
Once scheduled, jobs run autonomously. The OS wakes up the task at the designated time, runs the supervisor script, and executes opencode run with your prompt. You don’t need to keep your terminal or any Node.js process running.
| Platform | Backend | Status |
|---|---|---|
| macOS | launchd | Full support |
| Linux (systemd) | systemd --user | Full support |
| Linux (POSIX) | cron (crontab) | Fallback |
| Windows | schtasks (Task Scheduler) | Supported |
Supervised Execution (v1.2.0+)#
Scheduled runs are wrapped in a supervisor script that provides:
- No overlap protection — if a previous run is still active, the next scheduled tick is skipped
- Non-interactive mode — scheduled runs force
OPENCODE_PERMISSIONto deny interactive prompts, so jobs never hang waiting for user input - Configurable timeouts — set
timeoutSecondsto hard-stop runaway runs withSIGTERMfollowed bySIGKILL
Workdir Scoping#
Jobs are scoped by their working directory. This means different projects don’t collide — each project has its own isolated job definitions, locks, logs, and OS scheduler units.
Built-in Skill Template#
The plugin ships a @scheduled-job-best-practices skill template. Install it into any repo with a single command:
Install the scheduled job best practices skillThis writes the skill to .opencode/skill/scheduled-job-best-practices/SKILL.md, which you can then reference in your scheduled job prompts.
Installation#
Add the plugin to your opencode.json:
{
"plugins": ["opencode-scheduler"]
}That’s it. The plugin registers all its tools automatically on OpenCode startup.
Available Tools#
| Tool | Description |
|---|---|
schedule_job | Create a new scheduled job (natural language or cron) |
list_jobs | List all scheduled jobs, optionally across all scopes |
get_job | Fetch details and metadata for a job |
update_job | Update an existing job’s schedule, prompt, or timeout |
delete_job | Remove a scheduled job and its artifacts |
run_job | Execute a job immediately (fire-and-forget) |
job_logs | View the latest logs from a job |
get_version | Show scheduler and OpenCode versions |
get_skill | Get built-in skill templates |
install_skill | Install a built-in skill into your repo |
cleanup_global | Remove scheduler artifacts across all scopes |
Real-World Use Cases#
Autonomous Deal Hunting#
Schedule a daily job at 9am to search for standing desks under $300The agent browses marketplaces, filters results, and forwards the best deals to Telegram or Slack — all while you sleep.
Weekly Code Audits#
Schedule a job every Monday at 8am to summarize my GitHub notificationsGet a weekly digest of PRs, issues, and activity across your repositories.
Health Monitoring#
Schedule a job every 6 hours to check if my website is up and alert me on Slack if it's downNo need for a separate monitoring service — your own AI agent handles uptime checks.
Background Data Processing#
Schedule a daily job from /path/to/project to run my-taskOffload routine maintenance, token cleanup, or periodic documentation generation to autonomous background agents.
How It Works#
- You describe the job in natural language or provide a cron expression
- The plugin writes a job configuration file under
~/.config/opencode/scheduler/scopes/<scopeId>/jobs/ - It installs a native OS timer — a
.plistforlaunchd,.service+.timerforsystemd, or a Task Scheduler entry on Windows - At the scheduled time, the OS calls a supervisor script (
~/.config/opencode/scheduler/supervisor.pl) - The supervisor runs
opencode run -- "<prompt>", appends logs, and updates job metadata
Legacy note: pre-v1.2.0 jobs were stored in ~/.config/opencode/jobs/*.json. The delete_job and cleanup_global tools handle both scoped and legacy artifacts.
Troubleshooting#
If jobs aren’t running, verify the scheduler registration:
- macOS:
launchctl list | grep opencode - Linux:
systemctl --user list-timers | grep opencode - Windows:
schtasks /Query /TN "\\OpenCode\\opencode-job-*"
Check logs: Show logs for my-job inside OpenCode.
Make sure the working directory has the right opencode.json with your MCP server configurations — without them, MCP tools won’t be available during scheduled runs.
Philosophy#
OpenCode Scheduler is intentionally a thin wrapper. It doesn’t try to be a distributed job scheduler or a cloud cron replacement. Instead, it leverages the scheduling infrastructure that already exists on every major operating system, adding just enough supervision (no-overlap, timeouts, log aggregation) to make autonomous AI agents reliable enough for production use.
The result: you can set up autonomous AI agents in minutes, running on your own machine, with no additional infrastructure cost.