opencode-copilot-delegate

An OpenCode plugin that delegates tasks to GitHub Copilot CLI as background subprocesses.

Overview

This plugin registers three tools in OpenCode:

• copilot_delegate — Spawn copilot -p as a background subprocess. Returns a task_id immediately so the parent agent never blocks.
• copilot_output — Retrieve the structured result envelope for a completed or running delegation.
• copilot_cancel — Cancel a running delegation with SIGTERM → SIGKILL escalation.

When the subprocess completes, a <system-reminder> notification is injected into the parent session via client.session.prompt with noReply: false for the first notification per session and noReply: true for subsequent ones, so the agent sees the result without an unbounded reply chain.

Installation

// opencode.json
{
  "plugin": ["opencode-copilot-delegate"]
}

Optional: install the TUI half

The server plugin works by itself. To enable the /copilot-status terminal UI, also install the TUI half in OpenCode's TUI config:

// tui.jsonc
{
  "plugin": ["opencode-copilot-delegate/tui"]
}

Requires the copilot CLI to be on PATH. Install via:

# npm (recommended)
npm install -g @github/copilot

# Homebrew
brew install copilot-cli

# Install script (CI-friendly)
curl -fsSL https://gh.io/copilot-install | bash

Authentication

The plugin passes through your existing Copilot CLI auth. Token precedence:

COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN > ~/.copilot/auth

The plugin logs the resolved auth source (not the token value) at delegation start.

Tools

copilot_delegate

Arg	Type	Description
prompt	string	Required. The prompt to send to Copilot.
agent	string?	Optional. Copilot agent name (see tool description for available agents).
model	string?	Optional. Model override (e.g. claude-haiku-4.5).
add_dir	string[]?	Optional. Additional directories to allow Copilot to read.
allow_tool	string[]?	Optional. Tool patterns to allow.
deny_tool	string[]?	Optional. Tool patterns to deny.

Returns { task_id: string } — a cpl_-prefixed UUID.

copilot_output

Arg	Type	Description
task_id	string	Required. Task ID from copilot_delegate.
block	boolean?	Optional. Wait for completion before returning. Default false.
timeout_ms	number?	Optional. Max wait ms when block: true. Default 30000, max 120000.

Returns a structured envelope with status, final_message, tokens, tool_calls_summary, and more.

copilot_cancel

Arg	Type	Description
task_id	string	Required. Task ID to cancel.

Returns { cancelled: boolean; was_running: boolean }.

Scope Boundary

Task state is in-memory inside a single OpenCode process. Calling copilot_output from a different OpenCode process returns { status: 'unknown', error: 'task_id not found in this OpenCode process' }. Cross-process sharing is deferred to a future version.

Known Limitations

• Orphaned subprocesses (mitigated since v0.2.0): If OpenCode crashes mid-delegation, the copilot subprocess becomes orphaned. A PID-file reaper now scans <XDG_STATE_HOME>/opencode-copilot-delegate/orphans/ at every plugin init, probes the owning plugin's liveness, and reaps subprocesses whose plugin has exited. A strict identity gate (kernel-tracked comm + start time) prevents PID-reuse misfires.
• Prompt visibility in ps: The copilot CLI accepts the prompt as a command-line argument, which means the full prompt text appears in ps output for any user on the host. This is an upstream Copilot CLI behavior. Avoid delegating prompts that contain secrets or PII; pass sensitive material via files, env vars, or --secret-env-vars instead.
• No subprocess lifetime cap: A hung copilot subprocess stays in the registry as running indefinitely. Cancel manually via copilot_cancel. A configurable timeout is planned for v1.x.
• TUI half is opt-in: The package ships server and TUI entrypoints. Existing server-only installs continue to register the three tools; /copilot-status only appears when the TUI entrypoint is installed.
• RPC server cleanup is best-effort: The server half exposes a localhost-only RPC listener for the TUI and writes a per-session authenticated port file under <XDG_CACHE_HOME or ~/.cache>/opencode/copilot-delegate/. OpenCode's server plugin API has no dispose hook today, so cleanup is tied to process exit signals and the orphan-reaper posture covers missed shutdowns.

Versioning

Releases under 0.x are unstable and may include breaking changes between minor versions. Pin to an exact version in production:

"dependencies": {
  "opencode-copilot-delegate": "0.1.0"
}

1.0.0 will be cut once the public surface stabilizes.

Privacy

This plugin collects zero telemetry. It does not phone home, track usage, or log to remote services. All logging goes through client.app.log(...), which OpenCode handles locally per its own settings. The resolved auth token value is never logged — only the auth source name.

License

MIT © Marcus R. Brown