OpenCode Background Tasks Plugin

Run OpenCode agent tasks in parallel without blocking the current session.

Features

• Start tasks in background and keep working in the foreground
• Check status and progress snapshots
• Retrieve results with optional blocking wait
• Cancel running tasks

Installation

From npm

npm install @toninho09/opencode-background-tasks

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@toninho09/opencode-background-tasks"]
}

Local Development

Clone the repository:

git clone https://github.com/toninho09/opencode-background-tasks.git
cd opencode-background-tasks
npm install

Then create a symlink to your OpenCode plugins directory:

ln -s /path/to/opencode-background-tasks ~/.config/opencode/plugins/opencode-parallel-task

OpenCode will automatically load the plugin. The plugin uses TypeScript directly, so no build step is required.

Note: The plugin includes an opencode.json file that configures the plugin to load from the current directory. This file is required for local plugins to work properly.

Tools

background_task_start

Start a background task.

{
  "prompt": "Analyze the entire codebase structure...",
  "agent": "explore",
  "model": "gpt-5.2"
}

background_task_status

Check current task status.

{ "task_id": "bg_abc123" }

background_task_result

Get task output. Use block: true to wait.

{ "task_id": "bg_abc123", "block": true, "timeout": 60000 }

background_task_cancel

Cancel one task or all tasks.

{ "task_id": "bg_abc123" }

Notes

• Tasks are tracked in memory. If the plugin reloads, previously created task IDs are not available.
• The plugin uses OpenCode sessions under the hood, so results are pulled from session messages.

Development

# Install dependencies
npm install

# Type check (no build required)
npm run typecheck

The plugin is written in TypeScript and is loaded directly by OpenCode. TypeScript files are not compiled to JavaScript - OpenCode handles that automatically.

Publishing

1. Update version in package.json
2. Run npm run typecheck to verify types
3. Publish with npm publish

No build step is required as the plugin is distributed as TypeScript source.