opencode-background-agents

Persistent background delegation for OpenCode.

This plugin adds a small async workflow to OpenCode:

1. delegate(prompt, agent) starts a background subagent session
2. The main conversation keeps going
3. Results are saved to disk under ~/.local/share/opencode/delegations/<project-id>/
4. OpenCode gets notified when the background task finishes
5. delegation_read(id) restores the saved result on demand

The delegated run reuses the chosen subagent's model and prompt, but always disables file editing and shell tools. The result is a saved note, not a detached workspace mutation.

Install

Publish the package to npm, then add it to your OpenCode config:

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

OpenCode installs npm plugins automatically at startup.

Usage

The plugin adds three tools:

| Tool | Purpose | |------|---------| | delegate(prompt, agent) | Start a background subagent run and return immediately | | delegation_read(id) | Read the saved result for one delegation | | delegation_list() | List saved and in-flight delegations with prompt/result previews |

Example flow:

delegate(
  prompt="Summarize this repository in 5 bullets.",
  agent="agent-gpt-5.4-high"
)

When a run completes, the parent session receives a minimal <task-notification> with the delegation ID and status. When the last pending delegation finishes, the parent session also receives a small wake-up event so the main agent can continue.

Behavior

• Delegations are scoped to the root session tree.
• Results survive session compaction because they are persisted to disk.
• Background runs are read-only even when the chosen subagent is normally write-capable.
• Notifications report status only. They do not generate a second AI summary of the result.
• The default timeout is 1 hour.

Release

This repository is set up for npm publishing through GitHub Actions.

1. Update package.json version
2. Push a matching git tag such as v0.1.0
3. GitHub Actions runs typecheck, build, and npm publish

Required GitHub secret:

• NPM_TOKEN

Development

npm install
npm run typecheck
npm run build

The package entrypoint is src/index.ts.