Queue it. Schedule it. Retry it. Know what happened.
English | 简体中文
SuperTask turns one-off opencode run commands into durable Agent operations. It gives OpenCode agents a persistent SQLite queue, scheduling, retries, concurrency control, safe cancellation, execution history, and a local Web Dashboard.
OpenCode can run an Agent now. SuperTask makes sure the work is still tracked after the terminal closes, the process fails, or the machine restarts.
| If you need to... | Use |
|---|---|
| Run one Agent once | opencode run |
| Run a few fixed commands at fixed times | cron, launchd, systemd, or GitHub Actions |
| Restart a long-running process on a schedule | PM2 cron_restart |
| Manage changing Agent jobs with durable state, retries, priorities, and history | SuperTask |
SuperTask is not another wrapper around cron. Scheduled work becomes an ordinary durable queue task, so manual and scheduled jobs follow the same concurrency, retry, cancellation, dependency, and history rules.
| Capability | What it means |
|---|---|
| Durable queue | Tasks and every run survive process and machine restarts in SQLite WAL |
| Three schedule types | Cron, run-once delay, and fixed recurring interval |
| Automatic recovery | Retry budgets, exponential backoff, dead-letter state, and manual retry |
| Controlled execution | Global concurrency, priority ordering, dependencies, and global batch serialization |
| Project awareness | Each task keeps its OpenCode project directory, Agent, and explicit or default model |
| Safe process handling | Cancel and shutdown wait for the managed OpenCode process tree to stop |
| Observable runs | Session ID, exact reproducible command, model output, tools, errors, and raw JSONL |
| Local Dashboard | Create, schedule, inspect, retry, cancel, and diagnose from 127.0.0.1 |
VERSION="$(npm view opencode-supertask dist-tags.latest)"
npm install -g "opencode-supertask@$VERSION"
opencode plugin "opencode-supertask@$VERSION" --global --forcePinning the exact version keeps the OpenCode plugin, global CLI, and Gateway on the same build. Do not replace it with a bare package name or @latest in opencode.json.
supertask install # recommended: PM2 startup, crash recovery, and log rotationFor foreground development instead:
supertask gatewayThe plugin never installs global services during OpenCode startup. PM2 setup only happens when you explicitly run supertask install.
Create a SuperTask named "Review API errors".
Use the build agent in this project, retry twice, and run it now.
OpenCode receives eight native supertask_* plugin tools. The current project directory is taken from OpenCode's tool context rather than trusted from model input.
supertask status
supertask list --limit 10
supertask uiThe Dashboard opens at http://127.0.0.1:4680.
flowchart LR
A[OpenCode tools / CLI / Dashboard] --> B[SQLite task queue]
B --> C[Gateway]
C --> D[Worker]
C --> E[Scheduler]
C --> F[Watchdog]
D --> G[opencode run]
G --> H[Run history and session]
The single Gateway owns runtime state transitions. Clients create and manage work; only the Gateway marks runs started, completed, failed, retried, or cancelled.
Run a security review with agent build and model provider/model.
Every weekday at 9:00, create a report task for this project.
Show failed tasks in this project and retry the recoverable ones.
Check whether batch "release" is running in another project.
Available plugin tools:
supertask_add supertask_schedule supertask_status supertask_retry
supertask_list supertask_get supertask_next supertask_upgrade
# Queue work
supertask add --name "Security review" --agent build \
--prompt "Review authentication and authorization" \
--importance 5 --urgency 4 --max-retries 2 \
--retry-backoff 30s --timeout 30min
# Schedule work
supertask template add --name "Weekday report" --agent build \
--prompt "Summarize important project changes" \
--type cron --cron "0 9 * * 1-5"
# Inspect and recover
supertask status
supertask list --status failed --limit 20
supertask retry --id 42
supertask cancel --id 42Run supertask --help or supertask <command> --help for the complete command surface. CLI help and human-readable diagnostics support auto, en, and zh-CN.
The responsive Dashboard supports English and Chinese, light and dark themes, and four focused views:
| Page | Purpose |
|---|---|
| Task Queue | Browse projects, create/edit tasks, see priorities and active state, retry, cancel, or delete safely |
| Scheduled Tasks | Create/edit cron, delayed, and recurring templates; run one immediately without bypassing the queue |
| Execution Logs | Read structured output, tools, errors, sessions, and the exact historical command |
| System Status | Inspect active configuration, health, concurrency, and backup-first database maintenance |
The project picker reads the selected directory's real opencode agent list and opencode models output, so forms offer only locally available models and directly runnable Agents.
- SQLite
BEGIN IMMEDIATEprotects the single-Gateway lock and global batch serialization. - Each managed run has a unique launcher identity and an isolated Unix process group.
- A run settles only after the launcher proves the entire process group drained.
- Shutdown and cancellation fail closed when process ownership cannot be proven.
supertask doctorverifies OpenCode, the effective pinned plugin, cache, CLI, Gateway package, ready lock, SQLite, Dashboard, and PM2 environment.- Database clear and restore are transactional, backup-first, WAL-consistent, and reject active work.
The detailed guarantees and recovery rules live in Architecture and Operations and Troubleshooting.
supertask upgrade # update only when versions or components have drifted
supertask upgrade --force # reinstall the current version, refresh environment, restart
supertask doctor
supertask doctor --smoke --smoke-agent build --smoke-model provider/modelWhen every component already matches npm latest, normal upgrade is a no-op and does not restart the Gateway. Smoke diagnostics make one real model call; ordinary doctor does not.
- OpenCode
- Bun 1.1.45 or newer
- Node.js/npm for the documented install and upgrade flow
- macOS or Linux for Gateway task execution
Windows Worker execution remains disabled until OS Job Object containment can guarantee safe process-tree cancellation. Queue execution does not require PM2 when the Gateway runs in the foreground.
git clone https://github.com/vbgate/opencode-supertask.git
cd opencode-supertask
bun install
bun run buildPoint OpenCode at the built plugin file:
{
"plugin": [
"file:///home/user/src/opencode-supertask/dist/plugin/supertask.js"
]
}Then restart OpenCode and run bun run gateway from the repository.
- Tool descriptions include scheduling, retries, global batches, dependencies, and project-scope semantics.
- Plugin tools use the OpenCode context directory and reject a model-supplied working directory.
- Task-management commands return JSON, while database and doctor commands support explicit
--json; interactive summaries are concise and localized. AGENTS.mdrecords architecture invariants, testing rules, release rules, and unsafe shortcuts for coding agents.- Commands record exact executable, arguments, model, Agent, and working directory for reproducible diagnosis.
- Operations and troubleshooting
- Current architecture and decisions
- Changelog
- Documentation index
- Contributor and Agent rules
bun install --frozen-lockfile
bun test
bun run typecheck
bun run buildCI also runs the built launcher IPC smoke test on the minimum supported Bun version.
MIT