{"id":50594649,"url":"https://github.com/different-ai/opencode-scheduler","last_synced_at":"2026-06-05T13:01:25.344Z","repository":{"id":331944552,"uuid":"1127509991","full_name":"different-ai/opencode-scheduler","owner":"different-ai","description":"OpenCode plugin for scheduling recurring jobs using launchd (Mac) or systemd (Linux)","archived":false,"fork":false,"pushed_at":"2026-02-17T04:01:25.000Z","size":397,"stargazers_count":100,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-17T08:30:21.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/different-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-04T03:04:58.000Z","updated_at":"2026-02-17T04:01:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/different-ai/opencode-scheduler","commit_stats":null,"previous_names":["different-ai/opencode-scheduler"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/different-ai/opencode-scheduler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/different-ai%2Fopencode-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/different-ai%2Fopencode-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/different-ai%2Fopencode-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/different-ai%2Fopencode-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/different-ai","download_url":"https://codeload.github.com/different-ai/opencode-scheduler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/different-ai%2Fopencode-scheduler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33942436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-05T13:01:24.106Z","updated_at":"2026-06-05T13:01:25.324Z","avatar_url":"https://github.com/different-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-scheduler\n\nRun AI agents on a schedule. Set up recurring tasks that execute autonomously—even when you're away.\n\n```\nSchedule a daily job at 9am to search Facebook Marketplace for posters under $100 and send the top 5 deals to my Telegram\n```\n\nThis is an [OpenCode](https://opencode.ai) plugin that uses your OS's native scheduler (launchd on macOS, systemd on Linux, Task Scheduler on Windows), with cron fallback where native backends are unavailable.\n\nAs of `v1.2.0`, jobs are scoped by `workdir` (so different projects don't collide), and scheduled runs are supervised (no overlap + optional timeout).\n\n## Install\n\nAdd to your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"opencode-scheduler\"]\n}\n```\n\n## Examples\n\n**Daily deal hunting:**\n```\nSchedule a daily job at 9am to search for standing desks under $300\n```\n\n**Weekly reports:**\n```\nSchedule a job every Monday at 8am to summarize my GitHub notifications\n```\n\n**Recurring reminders:**\n```\nSchedule a job every 6 hours to check if my website is up and alert me on Slack if it's down\n```\n\n## Commands\n\n| Command | Example |\n|---------|---------|\n| Schedule a job | `Schedule a daily job at 9am to...` |\n| List jobs | `Show my scheduled jobs` |\n| Get version | `Show scheduler version` |\n| Install skill template | `Install the scheduled job best practices skill` |\n| Get job | `Show details for standing-desk` |\n| Update job | `Update standing-desk to run at 10am` |\n| Run immediately | `Run the standing-desk job now` |\n| View logs | `Show logs for standing-desk` |\n| Delete | `Delete the standing-desk job` |\n| Global cleanup (dry run) | `Run scheduler global cleanup` |\n\n## How It Works\n\n1. You describe what you want scheduled in natural language\n2. The plugin writes a job file (scoped by `workdir`) and installs a timer in your OS scheduler\n3. At the scheduled time, the OS scheduler calls a small supervisor script\n4. The supervisor runs the job, appends logs, and updates job metadata\n\nYou can also trigger a job immediately via `run_job`—it runs fire-and-forget and appends to the same log file.\n\nJobs run from the working directory where you created them, picking up your `opencode.json` and MCP configurations.\n\n### Reliability Guarantees (Scheduled Runs)\n\n- **No overlap**: if the previous run is still active, the next scheduled tick is skipped.\n- **Non-interactive by default**: scheduled runs force `OPENCODE_PERMISSION` to deny \"question\" prompts, so jobs don't hang waiting for approvals.\n- **Optional timeout**: set `timeoutSeconds` to hard-stop long runs (SIGTERM, then SIGKILL).\n\n### Platform Support\n\n| Platform | Scheduler backend | Notes |\n|------|------|------|\n| macOS | `launchd` | Full support (supervised scheduled runs) |\n| Linux (systemd available) | `systemd --user` | Full support (supervised scheduled runs) |\n| Linux / POSIX (no systemd) | `cron` (`crontab`) | Fallback backend (no missed-run catch-up) |\n| Windows | `schtasks` (Task Scheduler) | Supported with cron subset mapping (see limits below) |\n\nWindows Task Scheduler limits:\n\n- Cron expressions that use unsupported combinations (for example, month + weekday constraints, or month-only without explicit day-of-month) return a clear error with guidance.\n- Complex cron schedules may be expanded into multiple Windows tasks under `\\\\OpenCode\\\\opencode-job-...`.\n- Windows scheduled runs currently do **not** use the supervisor pipeline used on macOS/Linux, so no-overlap and timeout enforcement are not guaranteed by the OS integration itself.\n\n---\n\n## Reference\n\n### Cron Syntax\n\nJobs use standard 5-field cron expressions:\n\n```\n┌───────────── minute (0-59)\n│ ┌───────────── hour (0-23)\n│ │ ┌───────────── day of month (1-31)\n│ │ │ ┌───────────── month (1-12)\n│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)\n│ │ │ │ │\n* * * * *\n```\n\n| Expression | Meaning |\n|------------|---------|\n| `0 9 * * *` | Daily at 9:00 AM |\n| `0 */6 * * *` | Every 6 hours |\n| `30 8 * * 1` | Mondays at 8:30 AM |\n| `0 9,17 * * *` | At 9 AM and 5 PM daily |\n\n### Tools\n\n| Tool | Description |\n|------|-------------|\n| `schedule_job` | Create a new scheduled job |\n| `list_jobs` | List all scheduled jobs |\n| `get_version` | Show scheduler and opencode versions |\n| `get_skill` | Get built-in skill templates (best practices) |\n| `install_skill` | Install a built-in skill into your repo |\n| `get_job` | Fetch job details and metadata |\n| `update_job` | Update an existing job |\n| `delete_job` | Remove a scheduled job |\n| `cleanup_global` | Remove scheduler artifacts across all scopes (dry-run by default) |\n| `run_job` | Execute a job immediately (fire-and-forget) |\n| `job_logs` | View the latest logs from a job |\n\n`schedule_job` and `update_job` accept an optional `timeoutSeconds` (integer seconds). Use `0` (or omit) to disable.\n\nTools accept an optional `format: \"json\"` argument to return structured output with `success`, `output`, `shouldContinue`, and `data`.\n\n### Global Cleanup\n\nUse `cleanup_global` to clean scheduler artifacts across all scopes. It always starts in dry-run mode unless you pass `confirm: true`.\n\n- Dry run (safe default):\n\n```json\n{ \"confirm\": false }\n```\n\n- Execute global cleanup of job definitions + lock files + scheduler units:\n\n```json\n{ \"confirm\": true }\n```\n\n- Also delete logs and run history:\n\n```json\n{ \"confirm\": true, \"includeHistory\": true }\n```\n\nThe tool reports exactly how many artifacts were removed, grouped by location (jobs, locks, logs, runs, launchd/systemd units).\n\n### Storage\n\n| What | Where |\n|------|-------|\n| Job configs (scoped) | `~/.config/opencode/scheduler/scopes/\u003cscopeId\u003e/jobs/*.json` |\n| Run records (scoped) | `~/.config/opencode/scheduler/scopes/\u003cscopeId\u003e/runs/*.jsonl` |\n| Locks (scoped) | `~/.config/opencode/scheduler/scopes/\u003cscopeId\u003e/locks/*.json` |\n| Logs (scoped) | `~/.config/opencode/logs/scheduler/\u003cscopeId\u003e/*.log` |\n| Supervisor script | `~/.config/opencode/scheduler/supervisor.pl` |\n| launchd plists (Mac) | `~/Library/LaunchAgents/com.opencode.job.\u003cscopeId\u003e.*.plist` |\n| systemd units (Linux) | `~/.config/systemd/user/opencode-job-\u003cscopeId\u003e-*.{service,timer}` |\n| Task Scheduler entries (Windows) | `\\\\OpenCode\\\\opencode-job-\u003cscopeId\u003e-*` |\n\nLegacy note: older versions stored jobs in `~/.config/opencode/jobs/*.json` and used unscoped unit names. `delete_job` removes both scoped and legacy artifacts.\n\n### Working Directory\n\nJobs run from a specific directory to pick up MCP configs:\n\n```\nSchedule a daily job at 9am from /path/to/project to run my-task\n```\n\nBy default, jobs use the directory where you created them.\n\n### Scopes\n\nScopes are derived from the job's `workdir` (normalized absolute path). This isolates job storage, logs, and OS scheduler unit names per project.\n\n- `list_jobs` defaults to the **current scope** (your current working directory).\n- Use `allScopes: true` to list jobs across all scopes.\n- Use `includeLegacy: true` to include pre-`v1.2.0` jobs stored in `~/.config/opencode/jobs`.\n\n### Attach URL (optional)\n\nIf you have an OpenCode backend running via `opencode serve` or `opencode web`, you can set `attachUrl` on a job so runs use that backend:\n\n```\nUpdate the standing-desk job to use attachUrl http://localhost:4096\n```\n\n## Project Philosophy\n\n- This plugin is intentionally a thin wrapper: it schedules `opencode run` via launchd/systemd/schtasks, with cron fallback when native backends are unavailable.\n- Logs are the source of truth for scheduled runs: `~/.config/opencode/logs/*.log`.\n- Resiliency/reporting roadmap (not implemented): `PRD-resilient-execution.md`.\n\n### Built-in Skill Templates\n\nTo install the built-in skill into your project (no copy/paste), open OpenCode in your repo and run:\n\n```\nInstall the scheduled job best practices skill\n```\n\nThis calls the plugin’s `install_skill` tool and writes `.opencode/skill/scheduled-job-best-practices/SKILL.md`.\n\n(If you prefer, you can also say: `Get skill from opencode-scheduler and add it to my skills`.)\n\nThen add `@scheduled-job-best-practices` at the top of scheduled job prompts.\n\n(Manual option: use `get_skill` to fetch `scheduled-job-best-practices` and copy it into `.opencode/skill/scheduled-job-best-practices/SKILL.md`.)\n\n## Troubleshooting\n\n**Jobs not running?**\n\n1. Check if installed:\n   - Mac: `launchctl list | grep opencode`\n   - Linux: `systemctl --user list-timers | grep opencode`\n   - Windows: `schtasks /Query /TN \"\\\\OpenCode\\\\opencode-job-*\"`\n\n2. Check logs: `Show logs for my-job`\n\n3. Verify the working directory has the right `opencode.json` with MCP configs\n\n**MCP tools not available?**\n\nMake sure the job's working directory contains an `opencode.json` with your MCP server configurations.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdifferent-ai%2Fopencode-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdifferent-ai%2Fopencode-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdifferent-ai%2Fopencode-scheduler/lists"}