Skip to content
Showcase Ecosystem Source Code Docs

Background Agents

Background Agents

Background Agents brings Claude Code-style async delegation to OpenCode. Fire off research tasks, continue brainstorming or coding, and retrieve results when you need them. Results are saved to disk as markdown so they survive context compaction.

Key Features

FeatureDescription
Keep workingResearch runs in the background while you keep coding
Survive compactionResults saved to disk as markdown files
Fire and forget”Waiter model” — notification arrives when results are ready
Stable delegation IDsReused across state, artifact paths, notifications, and retrieval
Terminal-state protectionLate progress events cannot regress terminal status

How It Works

1. Delegate    →  "Research OAuth2 PKCE best practices"
2. Continue    →  Keep coding, brainstorming, reviewing
3. Notified    →  <task-notification> arrives on terminal state
4. Retrieve    →  AI calls delegation_read() to get the result

Results are persisted to ~/.local/share/opencode/delegations/ as markdown files.

Installation

ocx add kdco/background-agents --from https://registry.kdco.dev

Or install the full workspace bundle:

ocx add kdco/workspace --from https://registry.kdco.dev

Manual

Copy source files from src/ to .opencode/plugin/background-agents.ts. Requires manually installing the unique-names-generator dependency.

Tools

ToolPurpose
delegate(prompt, agent)Launch a background task
delegation_read(id)Retrieve a specific result
delegation_list()List all delegations with titles and summaries

Limitations

  • Read-only sub-agents only (edit=deny, write=deny, bash deny) — write-capable sub-agents must use the native task tool
  • 15-minute delegation timeout
  • Plugin-compatible lifecycle parity, not runtime-internal parity