> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Background Agents Plugin

> Async background delegation with persistent results that survive context compaction

## Overview

A plugin for OpenCode that enables async background delegation. Fire off research tasks, continue brainstorming or coding, and retrieve results when you need them. Results survive context compaction.

## Why This Exists

Context windows fill up. When that happens, compaction kicks in and your AI loses track of research it just did. Background agents solve this:

* **Keep working** — Delegate research and continue your conversation.
* **Survive compaction** — Results are saved to disk as markdown.
* **Fire and forget** — A notification arrives when your research is ready.

## Installation

```bash theme={null}
ocx add kdco/background-agents --from https://registry.kdco.dev
```

Or install the full [Workspace bundle](/docs/integrations/workspace):

```bash theme={null}
ocx add kdco/workspace --from https://registry.kdco.dev
```

## 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. Each delegation is automatically tagged with a title and summary.

## Lifecycle Behavior

The plugin now follows Claude Code's background-agent lifecycle as closely as possible within plugin boundaries:

* **Stable task IDs** across in-memory state, markdown artifact filename, notifications, and retrieval.
* **Explicit lifecycle transitions** (`registered` → `running` → terminal state).
* **Terminal-state protection** (late progress/idle events cannot overwrite terminal status).
* **Persistence-before-notify** (terminal markdown artifact is written before model-facing completion notification).
* **Blocking retrieval** (`delegation_read(id)` waits for terminal/timeout, then returns persisted output or deterministic terminal info).
* **Compaction carry-forward** for running and unread completed delegations with retrieval instructions.

## Tools

| Tool                      | Purpose                                        |
| ------------------------- | ---------------------------------------------- |
| `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

Only read-only sub-agents (permissions: `edit=deny`, `write=deny`, `bash={"*":"deny"}`) can use `delegate`.
Any write-capable sub-agent (any write/edit/bash allow) must use the native `task` tool.

**Why?** Background delegations run in isolated sessions outside OpenCode's session tree. The undo/branching system cannot track changes made in background sessions.

### Timeout

Delegations timeout after **15 minutes**.

### Claude Parity Boundaries

This is plugin-level parity, not runtime-internal parity. The plugin does **not** reproduce OpenCode/Claude runtime internals such as:

* internal AppState/task queue processors
* runtime notification priority controls
* write-capable background sessions with native undo/branching parity

Write-capable sub-agents still use native `task`. Read-only sub-agents use `delegate`.

### Real-Time Monitoring

View active and completed sub-agents using OpenCode's navigation shortcuts:

| Shortcut       | Action                 |
| -------------- | ---------------------- |
| `Ctrl+X Up`    | Jump to parent session |
| `Ctrl+X Left`  | Previous sub-agent     |
| `Ctrl+X Right` | Next sub-agent         |

## See Also

* [Workspace Integration](/docs/integrations/workspace) — Full multi-agent workspace bundle.
* [Notify Plugin](/docs/integrations/notify) — Get notified when delegations complete.
* [Worktree Plugin](/docs/integrations/worktree) — Isolated development environments.
* [KDCO Workspace Guide](/docs/guides/kdco-workspace) — Installation walkthrough.