Per-invocation background subagent execution for AI coding hosts — with a full TUI layer for live task control.
See the BG vs FG model, 3-level policy cascade, and v1.0 UX in a clickable walkthrough:
▶ Open interactive presentation
Works in any modern browser — no build, no install. Runs locally too: open docs/upstream/presentation/bg-vs-fg-interactive.html directly from disk.
bg-subagents intercepts every task call and routes it background or foreground based on your policy config. No picker required. The main conversation continues immediately; completion is delivered back as a bus event or synthetic assistant message. A sidebar and keyboard shortcuts give you live visibility directly in the OpenCode TUI.
New in v1.0: PolicyResolver (policy-driven routing, no picker), /task move-bg live control, TUI sidebar + Ctrl+B/F/↓ keybinds, zero-stdout guarantee, 788 tests.
OpenCode adapter v1.0 — shipping to npm.
@maicolextic/bg-subagents-protocol 1.0.0
@maicolextic/bg-subagents-core 1.0.0
@maicolextic/bg-subagents-opencode 1.0.0
Upgrading from v0.1? See the migration guide.
Claude Code adapter (v0.2) and MCP adapter (v0.3) are on the roadmap — not shipped yet.
# pnpm
pnpm add @maicolextic/bg-subagents-opencode
# npm
npm install @maicolextic/bg-subagents-opencode
# yarn
yarn add @maicolextic/bg-subagents-opencodev1.0 uses the OpenCode server plugin plus an optional TUI plugin.
~/.config/opencode/opencode.json (or project-local opencode.json):
{
"plugin": [
"@maicolextic/bg-subagents-opencode"
]
}~/.config/opencode/tui.json (or project-local tui.json) — for sidebar + keybinds:
{
"plugin": [
{
"module": "@maicolextic/bg-subagents-opencode/tui"
}
]
}The server plugin is functional standalone. The TUI entry is optional but recommended for live task visibility.
See packages/opencode/README.md for the full configuration reference, policy JSONC format, and troubleshooting guide.
OpenCode will call (await import("@maicolextic/bg-subagents-opencode")).default.server(ctx) at session start and register the returned hooks automatically.
Once the plugin is registered, routing is policy-driven. Configure SDD agents in ~/.config/bg-subagents/policy.jsonc:
Background agents are rewritten to task_bg and return a task_id immediately. Foreground agents remain native task calls and block by design.
You can also call task_bg directly in your prompts:
You: task_bg subagent_type=researcher prompt="audit src/ for N+1 queries"
→ { "task_id": "tsk_a1b2c3d4", "status": "running" }
Use /task slash-commands to inspect and manage background tasks:
| Command | Description |
|---|---|
/task list |
List all tasks (running + history). |
/task show <id> |
Show full detail for a specific task. |
/task kill <id> |
Send an abort signal to a running task. |
/task logs <id> |
Stream the JSONL log lines for a task. |
| Flag | Applies to | Description |
|---|---|---|
--status=<value> |
list |
Filter by status. Values: running, completed, killed, killed_on_disconnect, error, cancelled, passthrough, rejected_limit. |
--agent=<name> |
list |
Filter by spawning-agent name (case-insensitive substring match). |
--since=<value> |
list |
Filter to tasks started on or after a timestamp. Accepts ISO-8601 (2025-04-01T00:00:00Z) or duration shorthands (1h, 30m, 7d, 60s). |
--tail=<N> |
logs |
Show only the last N log lines. |
--no-color |
all | Suppress ANSI color codes (useful for piping). |
/task list --status=running
/task list --agent=researcher --since=1h
/task logs tsk_a1b2c3d4 --tail=50
/task kill tsk_a1b2c3d4
Create ~/.config/bg-subagents/policy.jsonc to customize behavior:
{
"$schema": "https://maicololiveras.github.io/bg-subagents/schema/policy-v1.json",
// Per-name override — highest precedence
"default_mode_by_agent_name": {
"researcher": "background",
"reviewer": "foreground"
},
// Per-type default — middle precedence
"default_mode_by_agent_type": {
"subagent": "background",
"tool": "foreground"
},
// Picker timeout in ms (default: 2000). 0 = no timeout.
"timeout_ms": 3000,
// RESERVED in v0.1 — activated in v0.2/v0.3
"security": {
"max_concurrent_bg_tasks": 4,
"timeout_per_task_ms": 300000,
"blocked_tools_in_bg": ["bash", "write_file"]
},
// History rotation
"history": {
"rotation_size_mb": 20,
"retention_days": 14
},
// Telemetry (off by default)
"telemetry": {
"enabled": false
}
}See docs/policy-schema.md for the full field reference.
A task is routed differently than expected.
Check ~/.config/bg-subagents/policy.jsonc. Canonical modes are background and foreground; legacy bg and fg are accepted and normalized.
Protocol version mismatch warning on startup.
Your installed @maicolextic/bg-subagents-protocol and the OpenCode adapter use different MAJOR versions. A MAJOR mismatch is a hard error; a MINOR mismatch is a warning. Run pnpm update @maicolextic/bg-subagents-opencode to align.
task_bg tool does not appear in the model's context.
The system prompt hook only injects the tool description if the plugin booted successfully for the current session. Check the OpenCode plugin log for plugin:booted or look for boot errors. Ensure the plugin is listed in opencode.json under the plugin array.
Where are the task logs stored?
JSONL logs live at ~/.local/share/bg-subagents/history/ (Linux/Mac) or %APPDATA%\bg-subagents\history\ (Windows). Files rotate at 10 MB by default and are retained for 30 days.
v0.2 — Claude Code adapter. Hooks into the Claude Code plugin surface; same picker + invoker stack, same /task commands. Protocol stays 1.x; security.limits enforcement activates.
v0.3 — MCP adapter. Exposes task_bg as a native MCP tool, enabling background subagents from any MCP-compatible host. mcp.grace_period_ms activates.
| Doc | What it covers |
|---|---|
| packages/opencode/README.md | Full plugin reference: install, config, /task commands, policy JSONC, TUI keybinds, troubleshooting |
| docs/installation.md | Consolidated installation guide (npm, gentle-ai, local dev, verification, troubleshooting) |
| docs/integrations/gentle-ai.md | Gentle-AI integration status, mechanism, and upstream PR info |
| docs/INDEX.md | Full docs index — navigation aid for all docs |
| docs/architecture.md | Component diagram, hook wiring table, data flow, SharedPluginState bridge |
| docs/migration-v0.1-to-v1.0.md | Breaking changes from v0.1, upgrade steps, rollback instructions |
| docs/policy-schema.md | Full policy JSONC field reference |
| docs/release-process.md | Changesets, publish workflow, versioning |
Contributions are welcome on the main branch. Run pnpm test and pnpm -r typecheck before submitting a PR. See docs/architecture.md for the design overview and docs/release-process.md for how changesets and publish work.
MIT. See LICENSE.
{ "default_mode_by_agent_name": { "sdd-explore": "background", "sdd-apply": "foreground", "sdd-verify": "foreground" } }