User Guide

User Guide

Install and upgrade

Use OpenCode's plugin installer so the scheduling server and interactive TUI entrypoints are both detected:

opencode plugin opencode-plugin-loop --global --force

The command adds the unversioned package name to the global server and TUI configurations. Run the same command whenever a newer npm release is available, then restart OpenCode.

OpenCode currently does not copy the bundled commands/loop.md into your configuration. If /loop is not already registered, add the command definition below.

Configuration

Server configuration: ~/.config/opencode/opencode.json

{
  "plugin": ["opencode-plugin-loop"],
  "command": {
    "loop": {
      "description": "Run a prompt repeatedly on a schedule. Optional intervals: s/m/h/d. Subcommands: list, status, cancel, pause, resume, stop-all.",
      "template": "$ARGUMENTS",
      "agent": "build"
    }
  },
  "opencode-plugin-loop": {
    "maxTasks": 50,
    "taskTtlDays": 7,
    "defaultAdaptiveMinMs": 60000,
    "defaultAdaptiveMaxMs": 3600000,
    "tickerIntervalMs": 5000
  }
}

TUI configuration: ~/.config/opencode/tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-plugin-loop"]
}

Configuration defaults:

Option	Default	Purpose
maxTasks	50	Maximum number of stored tasks
taskTtlDays	7	Remove expired tasks when state is loaded
defaultAdaptiveMinMs	60000	Minimum adaptive delay: 1 minute
defaultAdaptiveMaxMs	3600000	Maximum adaptive delay: 1 hour
tickerIntervalMs	5000	How often the scheduler checks for due tasks

Loop modes

Fixed interval

Place an interval before the prompt. Seconds, minutes, hours, and days are supported.

/loop 5m check whether the deployment finished
/loop 30s check the health endpoint
/loop 2h look for failing CI runs

Adaptive interval

Omit the interval. The model receives the prompt on every run and can use loop_schedule to choose the next delay within the configured adaptive range.

/loop check whether CI passed and address review comments

Bare /loop

Run /loop without arguments to load maintenance instructions from .opencode/loop.md in the project or ~/.opencode/loop.md for the user. If neither file exists, the plugin uses its built-in maintenance prompt.

/loop

Manage tasks

Commands are session-scoped by default. Add --all only when you intentionally need to inspect or modify tasks from other sessions.

/loop list
/loop list --all
/loop status
/loop cancel <taskId>
/loop cancel <taskId> --all
/loop pause <taskId>
/loop resume <taskId>
/loop stop-all
/loop stop-all --all

A cross-session operation without --all is rejected and returns a hint rather than changing another session's task.

Interactive result dialog

Every /loop result opens in a native dialog. The available actions are:

• Copy ID: <taskId> — copy one displayed task ID.
• Copy all — copy the complete result text exactly as shown.
• Close — dismiss the current result.

Controls:

• Up/Down and Tab/Shift+Tab move selection.
• Enter, Space, or a mouse click activates the selected row.
• Mouse hover selects the row under the pointer.
• Page Up/Page Down scroll long result text.
• Copy ID and Copy all close after a successful copy.
• Clipboard failure keeps the dialog open and displays an error.
• q and Esc close the dialog.

The dialog scales to short or narrow terminals. Its result and action areas scroll independently, and a newer Loop result replaces the previous dialog instead of stacking another one.

LLM tools

The plugin registers loop_schedule and loop_status. OpenCode supplies the current session ID through tool context, so normal calls remain session-bound.

loop_schedule({
  action: "create",
  prompt: "check the deployment",
  intervalMs: 300_000,
})

loop_schedule({
  action: "cancel",
  taskId: "abc12345",
})

loop_schedule({
  action: "reschedule",
  taskId: "abc12345",
  nextDueAtMs: Date.now() + 5 * 60_000,
})

loop_status({})
loop_status({ all: true })

Use all: true only when cross-session access is intended.