OpenCode Background Agents Plugin

Background agents solve the problem of context window exhaustion and compaction.

Persistence Mechanism:

• Results are saved to disk as markdown files in ~/.local/share/opencode/delegations/.
• Each delegation is automatically tagged with a title and summary.
• When context is compacted, the AI can use delegation_list() to scan past research and delegation_read(id) to retrieve specific results from disk.
• Data survives session restarts and process crashes.

The delegate tool can only be used by read-only sub-agents.

Required Permissions:

• edit=deny
• write=deny
• bash={"...":"deny"}

Why? Background delegations run in isolated sessions outside OpenCode's session tree. The undo/branching system cannot track changes made in background sessions, so write-capable agents must use the native task tool to avoid data loss.

If you prefer not to use OCX, you can manually install the plugin by copying the source files from the src/ directory to .opencode/plugin/background-agents.ts.

Important Caveats:

• You must manually install dependencies, specifically unique-names-generator.
• Updates must be handled manually by re-copying files.

To install the background agents plugin, use the ocx add command pointing to the KDCO registry.

Note: This project is retired and intended for OpenCode V1 only. For OpenCode V2, use native background subagents. If you are using OpenCode V1, use OCX 2.0.15.

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

For a bundled experience including background agents, specialist agents, planning tools, and research protocols, install kdco/workspace via the KDCO registry.

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

The plugin provides three primary tools for managing asynchronous research tasks:

Workflow:

1. Delegate: Call delegate with a prompt and an agent to start research.
2. Continue: Continue your main conversation/coding while the task runs.
3. Notified: A <task-notification> arrives in the terminal state when finished.
4. Retrieve: Call delegation_read(id) to get the results.

Users should be aware of the following operational constraints:

• Timeout: All delegations timeout after 15 minutes.
• Upstream Parity: This plugin provides lifecycle parity within OpenCode plugin boundaries, but it does not replicate Claude/OpenCode internal AppState, task queue internals, or runtime notification priority controls.
• Write Capabilities: Write-capable sub-agents should continue to use the native task tool instead of delegate.

You can navigate between active and completed sub-agents using OpenCode's navigation shortcuts:

Use withTimeout to wrap an asynchronous operation with a time limit. If the operation exceeds the limit, it will throw a TimeoutError.

import { withTimeout, TimeoutError } from 'kdco-primitives';

try {
  await withTimeout(async () => {
    // Your long-running task here
  }, 5000); // 5 second timeout
} catch (e) {
  if (e instanceof TimeoutError) {
    console.error('Operation timed out');
  }
}

Use getTempDir to retrieve a path to a temporary directory suitable for plugin operations.

import { getTempDir } from 'kdco-primitives';

const tempPath = getTempDir();

Use logWarn to emit warning messages. This provides a consistent logging interface for plugins within the kdco registry.

import { logWarn } from 'kdco-primitives';

logWarn('This is a warning message');

Use these utilities to ensure shell commands are safely escaped before execution, preventing injection attacks or syntax errors across different operating systems and shells.

• escapeBash: For Bash environments.
• escapeAppleScript: For AppleScript.
• escapeBatch: For Windows Batch environments.
• assertShellSafe: Validates if a string is safe for shell execution.

import { escapeBash, escapeBatch, assertShellSafe } from 'kdco-primitives';

const safeBash = escapeBash('my argument');
const safeBatch = escapeBatch('my argument');
assertShellSafe('simple-command');