{"id":45475197,"url":"https://github.com/kdcokenny/opencode-background-agents","last_synced_at":"2026-02-22T14:54:13.963Z","repository":{"id":332025874,"uuid":"1125475343","full_name":"kdcokenny/opencode-background-agents","owner":"kdcokenny","description":"Claude Code-style background agents for OpenCode – async delegation with context persistence","archived":false,"fork":false,"pushed_at":"2026-01-22T15:12:23.000Z","size":80,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T05:35:46.642Z","etag":null,"topics":["ai-agents","async","background-agents","claude-code","delegation","ocx","opencode","opencode-plugin","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/kdcokenny/ocx","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kdcokenny.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T19:46:47.000Z","updated_at":"2026-01-22T15:14:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kdcokenny/opencode-background-agents","commit_stats":null,"previous_names":["kdcokenny/opencode-background-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kdcokenny/opencode-background-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdcokenny%2Fopencode-background-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdcokenny%2Fopencode-background-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdcokenny%2Fopencode-background-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdcokenny%2Fopencode-background-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdcokenny","download_url":"https://codeload.github.com/kdcokenny/opencode-background-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdcokenny%2Fopencode-background-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29716358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T13:30:57.152Z","status":"ssl_error","status_checked_at":"2026-02-22T13:30:28.561Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","async","background-agents","claude-code","delegation","ocx","opencode","opencode-plugin","typescript"],"created_at":"2026-02-22T14:54:13.456Z","updated_at":"2026-02-22T14:54:13.952Z","avatar_url":"https://github.com/kdcokenny.png","language":"TypeScript","readme":"# opencode-background-agents\n\n\u003e Keep working while research runs in the background. Your work survives context compaction.\n\nA plugin for [OpenCode](https://github.com/sst/opencode) that enables async background delegation. Fire off research tasks, continue brainstorming or coding, and retrieve results when you need them.\n\n## Why This Exists\n\nContext windows fill up. When that happens, compaction kicks in and your AI loses track of research it just did. You end up re-explaining, re-researching, starting over.\n\nBackground agents solve this:\n\n- **Keep working** - Delegate research and continue your conversation. Brainstorm, code review, discuss architecture - you're not blocked waiting.\n- **Survive compaction** - Results are saved to disk as markdown. When context gets tight, the AI knows exactly where to retrieve past research.\n- **Fire and forget** - Use the \"waiter model\": you don't follow the waiter to the kitchen. A notification arrives when your order is ready.\n\n## Installation\n\nInstall via [OCX](https://github.com/kdcokenny/ocx), the package manager for OpenCode extensions:\n\n```bash\n# Install OCX\ncurl -fsSL https://ocx.kdco.dev/install.sh | sh\n\n# Add the registry and install\nocx registry add https://registry.kdco.dev --name kdco\nocx add kdco/background-agents\n```\n\n\u003e **Tip:** Add `--global` to configure the registry globally instead of per-project.\n\nWant the full experience? Install `kdco-workspace` instead - it bundles background agents with specialist agents, planning tools, and research protocols:\n\n```bash\nocx add kdco/workspace\n```\n\n## How It Works\n\n```\n1. Delegate    →  \"Research OAuth2 PKCE best practices\"\n2. Continue    →  Keep coding, brainstorming, reviewing\n3. Notified    →  \u003csystem-reminder\u003e tells you it's done\n4. Retrieve    →  AI calls delegation_read() to get the result\n```\n\nResults are persisted to `~/.local/share/opencode/delegations/` as markdown files. Each delegation is automatically tagged with a title and summary, so the AI can scan past research and find what's relevant.\n\n## Usage\n\nThe plugin adds three tools:\n\n| Tool | Purpose |\n|------|---------|\n| `delegate(prompt, agent)` | Launch a background task |\n| `delegation_read(id)` | Retrieve a specific result |\n| `delegation_list()` | List all delegations with titles and summaries |\n\n## Limitations\n\n### Read-Only Agents Only\n\nOnly read-only agents (`researcher`, `explore`) can use `delegate`. Write-capable agents (`coder`, `scribe`) must use the native `task` tool.\n\n**Why?** Background delegations run in isolated sessions outside OpenCode's session tree. The undo/branching system cannot track changes made in background sessions—reverting would not affect these changes, risking unexpected data loss.\n\n\u003e A workaround is being explored.\n\n### Timeout\n\nDelegations timeout after **15 minutes**.\n\n### Real-Time Monitoring\n\nView active and completed sub-agents using OpenCode's navigation shortcuts:\n\n| Shortcut | Action |\n|----------|--------|\n| `Ctrl+X Up` | Jump to parent session |\n| `Ctrl+X Left` | Previous sub-agent |\n| `Ctrl+X Right` | Next sub-agent |\n\n## FAQ\n\n### How does the AI know what each delegation contains?\n\nEach delegation is automatically tagged with a title and summary when it completes. When the AI calls `delegation_list()`, it sees all past research with descriptions - not just opaque IDs. This lets it scan for relevant prior work and retrieve exactly what it needs.\n\n### Does this persist after the session ends?\n\nResults are saved to disk and survive context compaction, session restarts, and process crashes. Within a session, the AI can retrieve any past delegation. New sessions start fresh but the files remain on disk.\n\n### Does this bloat my context?\n\nThe opposite - it *saves* context. Heavy research runs in a separate sub-agent session. Only the distilled result comes back to your main conversation when you call `delegation_read()`.\n\n### How is this different from Claude Code's Task tool?\n\nClaude's native task tool runs sub-agents but results can be lost when context compacts. This plugin adds a persistence layer - results are written to markdown files, so the AI always knows where to find them.\n\n### Why install via OCX?\n\nOne command, auto-configured, registry-backed updates. You could copy the files manually, but you'd need to handle dependencies (`unique-names-generator`) and updates yourself.\n\n## Manual Installation\n\nIf you prefer not to use OCX, copy the source files from [`src/`](./src) to `.opencode/plugin/background-agents.ts`.\n\n**Caveats:**\n- Manually install dependencies (`unique-names-generator`)\n- Updates require manual re-copying\n\n## Part of the OCX Ecosystem\n\nThis plugin is part of the [KDCO Registry](https://github.com/kdcokenny/ocx/tree/main/registry/src/kdco). For the full experience, check out [kdco-workspace](https://github.com/kdcokenny/ocx) which bundles background agents with specialist agents, planning tools, and notification support.\n\n## Disclaimer\n\nThis project is not built by the OpenCode team and is not affiliated with [OpenCode](https://github.com/sst/opencode) in any way.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdcokenny%2Fopencode-background-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdcokenny%2Fopencode-background-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdcokenny%2Fopencode-background-agents/lists"}