opencode-muse-agents

Run subagents that survive crashes, respect capacity, and return results you can trust. This plugin ports Muse Code's coordination core to OpenCode: every spawn, steer, message, and verdict is a validated ledger record, not a live-session hope.

• Durable children: each worker is a committed record with lineage, worktree, and completion contract; lifecycle runs through 8 control statuses (src/child.ts: CONTROL_STATUS).
• Ledger mailbox: messages append first, then admit; delivery uses a closed set of 9 policies (src/mailbox.ts: DELIVERY_POLICIES); unknown combos fail closed.
• Admission control: spawns pass resolve, capacity, and depth gates mapped from 12 Agent RPC verbs (src/verbs.ts: AGENT_VERBS); rejections are keyed errors, never prose.
• Bounded results: worker envelopes cap summary at 512 chars and text at 32 KiB (src/envelope.ts: SUMMARY_MAX_CHARS, RESULT_TEXT_MAX_BYTES); over-cap input is rejected, never truncated.

Install

npm plugin (recommended):

npm i opencode-muse-agents

{ "plugin": ["opencode-muse-agents"] }

Copy-install (no npm):

cp -r bundle/agents bundle/tools bundle/plugins bundle/skills bundle/commands .opencode/
scripts/merge-fragment.sh ./opencode.json

scripts/merge-fragment.sh [TARGET] deep-merges bundle/opencode.fragment.json (agents, subagent_depth: 2, skill permissions) into your opencode.json, backs up the target first, and is a no-op on re-run. Details in bundle/README.md.

Quickstart (60 seconds)

1. /spark-plan <goal> — decompose into worker-sized units with inputs, worktree, budget, and evidence.
2. /spark-start — coordinator admits each worker via spark_submit, fans out, steers by mailbox notes only.
3. /spark-review <output> — reviewer gates every result; integrate only accepted work in your session.

Retry rule: same commandId to reconcile, never a new one. Workers never redelegate.

Coordinator loop:

flowchart TD
    Plan["spark-plan decomposes goal"]
    Submit["spark_submit admits spawn"]
    Fanout["task fan-out runs workers"]
    Send["spark_send steers by notes"]
    Worker["spark-worker executes unit"]
    Result["spark_result validates envelope"]
    Review["spark-reviewer gates result"]
    Integrate["integrate accepted work"]
    Plan --> Submit
    Submit --> Fanout
    Fanout --> Worker
    Send --> Worke