opencode-routines

Claude-Code-style routines for OpenCode: same-session loops, same-session cron prompts, and host-backed standalone scheduled agents.

Use it for things like:

/loop 5m /babysit-prs

Create a standalone scheduled run every weekday at 9am to summarize my open PRs

Create a same-session cron prompt for 17 * * * * to check whether CI is done

Install

Add the server plugin to your OpenCode config (~/.config/opencode/opencode.jsonc or project-level .opencode/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-routines@latest"]
}

OpenCode installs the package from npm on next start. Use @latest if you want new versions on restart, or pin a version such as "[email protected]".

That single entry is the whole packaged experience: on load, the server plugin also installs slash commands (/loop, /loops, /stop-loop, /schedule-standalone-session) as managed OpenCode custom command files under ~/.config/opencode/commands/, plus a discoverable standalone-scheduled-sessions skill under ~/.config/opencode/skill/ for investigating recurring scheduled runs. These work in both the terminal TUI and OpenCode Desktop. The install is idempotent and marker-guarded: only files containing the managed-by: opencode-routines marker are ever created or updated, so user-owned command/skill files with the marker removed are never touched. Restart OpenCode once after the first install for commands and skills to appear. Opt out with plugin options:

{
  "plugin": [["opencode-routines@latest", { "commands": false, "skills": false }]]
}

What it provides

| Capability | Session model | Where it runs | Persistence | Primary tools / commands | |---|---|---|---|---| | Loop | Same conversation | Current OpenCode host/process | Process-scoped | LoopCreate, LoopList, LoopDelete, ScheduleWakeup, /loop | | Cron prompt | Same conversation | Current OpenCode host/process | Session-only for now | CronCreate, CronList, CronDelete | | Standalone schedule | Fresh standalone opencode run | Host scheduler: launchd, systemd, Task Scheduler, or cron | Durable | ScheduleCreate, ScheduleList, ScheduleDelete, ScheduleRun, ScheduleLogs |

The ambiguous /schedule slash command is intentionally not registered. Use ScheduleCreate for durable standalone schedules, or /schedule-standalone-session for TUI help.

Discoverable skills

The plugin includes built-in skills that can be copied into a repo with install_skill and, for globally useful troubleshooting, installed automatically into the user's OpenCode config.

| Skill | Purpose | Install behavior | |---|---|---| | standalone-scheduled-sessions | Investigate recurring OpenCode sessions, list durable standalone schedules across all scopes, inspect logs, and safely delete jobs. | Auto-installed globally under ~/.config/opencode/skill/standalone-scheduled-sessions/SKILL.md. | | scheduled-job-best-practices | Prompt patterns for resilient non-interactive scheduled jobs. | Available via get_skill / install_skill. |

Use the standalone-scheduled-sessions skill when you see unexpected sessions from opencode session list or need to inventory ScheduleCreate / schedule_job jobs across folders.

Same-session loops

Loops run prompts back into the current conversation.

Fixed interval loop

/loop 5m /babysit-prs

Equivalent tool shape:

{
  "prompt": "/babysit-prs",
  "interval": "5m"
}

Dynamic loop

Dynamic loops are self-paced. The first prompt fires immediately, then the model can call ScheduleWakeup to decide when to resume.

/loop /babysit-prs

ScheduleWakeup parameters:

| Param | Type | Required | Description | |---|---|---|---| | delaySeconds | number | yes | Seconds until wake-up. Clamped to 60-3600. | | prompt | string | yes | The active loop prompt to fire on wake-up. | | reason | string | yes | Short explanation for the wake-up. |

Omitting ScheduleWakeup ends a dynamic loop.

Same-session cron prompts

Cron prompts enqueue prompts into the current session at wall-clock times. They are not standalone processes and do not run while OpenCode is closed.

Tools:

| Tool | Description | |---|---| | CronCreate | Schedule a prompt at wall-clock times in the current session. | | CronList | List active same-session cron prompts. | | CronDelete | Cancel a same-session cron prompt. |

CronCreate parameters:

| Param | Type | Required | Default | Description | |---|---|---|---|---| | cron | string | yes | — | 5-field cron in local timezone: M H DoM Mon DoW. | | prompt | string | yes | — | Prompt to enqueue in the same session. | | recurring | boolean | no | true | false makes a one-shot cron prompt. | | durable | boolean | no | false | Accepted for Claude compatibility, but currently session-only. |

Durable standalone schedules

Standalone schedules are independent opencode run processes launched by the host scheduler. They survive terminal exit and machine restarts according to the host scheduler's behavior.

Claude-aligned tools:

| Tool | Description | |---|---| | ScheduleCreate | Create a durable host-backed standalone scheduled OpenCode run. | | ScheduleList | List standalone schedules. | | ScheduleDelete | Delete a standalone schedule. | | ScheduleRun | Run a standalone schedule immediately. | | ScheduleLogs | View logs for a standalone schedule. |

Legacy compatibility tools from opencode-scheduler are still present: schedule_job, list_jobs, get_job, update_job, delete_job, run_job, job_logs, and cleanup_global.

TUI slash commands

Available after the managed command files have been installed (see Install above):

| Command | Meaning | |---|---| | /loop | Start a same-session live loop. Fixed interval syntax: 5m /babysit-prs; dynamic syntax: /babysit-prs. | | /loops | List active loops. Selecting a loop stops it. | | /stop-loop | Stop an active loop. | | /schedule-standalone-session | Help entry for durable standalone schedules. |

Storage and platform support

Standalone schedule storage remains compatible with opencode-scheduler:

| What | Where | |---|---| | Job configs | ~/.config/opencode/scheduler/scopes/<scopeId>/jobs/*.json | | Run records | ~/.config/opencode/scheduler/scopes/<scopeId>/runs/*.jsonl | | Locks | ~/.config/opencode/scheduler/scopes/<scopeId>/locks/*.json | | Logs | ~/.config/opencode/logs/scheduler/<scopeId>/*.log | | Supervisor script | ~/.config/opencode/scheduler/supervisor.pl |

Standalone schedule backends:

| Platform | Backend | |---|---| | macOS | launchd | | Linux with systemd | systemd --user | | Linux / POSIX fallback | cron | | Windows | Task Scheduler (schtasks) |

Compatibility notes

• Requires OpenCode 1.17.3 or newer.
• OpenCode loads config once at startup. Restart OpenCode after changing plugin configuration.
• CronCreate({ durable: true }) is accepted for Claude Code compatibility but currently behaves as session-only.

Debugging

• Use LoopList and CronList for live same-session state.
• Use ScheduleList and ScheduleLogs for durable standalone schedules.
• Standalone run logs live under ~/.config/opencode/logs/scheduler/<scopeId>/.

Development

npm install
npm test
npm run typecheck

For local development, point OpenCode at this repo's built files or source path. Do not load both a local shim and the npm package at the same time, or tools may register twice.

Publishing

This package publishes through GitHub Actions trusted publishing from .github/workflows/publish.yml.

For maintainer release steps and verification, use:

• .claude/skills/publish-package/SKILL.md

Credits

opencode-routines is a hard fork / successor of opencode-scheduler by Benjamin Shafii. The host-backed standalone scheduling implementation is derived from that project; this fork adds the routines-oriented model, same-session loops, cron prompts, and Claude-aligned tool names.

License

MIT