opencode-beads

OpenCode plugin for Beads — the Dolt-powered issue tracker for AI agents. Provides typed beads_* tools that wrap the modern bd 1.0+ CLI and one slash command, /beads:wizard, that helps the user pick a setup by consulting the live beads documentation.

Install

Add to your OpenCode plugin config:

• @abix5/opencode-beads (latest)
• or pin: @abix5/[email protected]

Restart OpenCode after adding or updating.

If OpenCode keeps loading a stale cached build:

rm -rf ~/.cache/opencode/node_modules/@abix5/opencode-beads
rm -f ~/.cache/opencode/bun.lock ~/.cache/opencode/package.json

Requirements

• bd CLI 1.0.0 or newer (install: brew install beads or curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash).
• A git repository for the project you want to track.

The plugin never passes the removed --no-daemon flag and refuses to run bd directly via bash — agents must go through the typed tools.

Typed tools

Lifecycle:

• beads_prime — agent manual: how to use the rest of the tools.
• beads_init — bd init (idempotent: skips if .beads/ already exists).
• beads_doctor — bd doctor, optional fix: true.
• beads_status — DB overview.

Issues:

• beads_create — create with optional deps (e.g. discovered-from).
• beads_update — title / status / priority / parent / assignee / labels.
• beads_claim — atomic claim (compare-and-swap).
• beads_close / beads_reopen — bulk-capable.
• beads_show / beads_list / beads_ready / beads_blocked.
• beads_search (free text) / beads_query (bd query language).

Dependencies:

• beads_dep_add / beads_dep_remove — types: blocks, parent-child, related, discovered-from.
• beads_graph — depth/direction-bounded dependency graph.

Comments and memory:

• beads_comment (use [progress] [decision] [risk] [blocker] [handoff] tags).
• beads_comments_list.
• beads_remember / beads_memories — cross-session persistent insights.

Sync:

• beads_dolt — push, pull, status, log, commit.

Workflow primitives (bd 1.0+):

• beads_formula_list — list workflow templates.
• beads_pour — instantiate a formula into a persistent molecule.
• beads_mol — list / bond / squash / burn / wisp_list / wisp_create / wisp_gc.
• beads_gate — create / approve / list / show / cancel (human, timer, github gates).

Escape hatch:

• beads_run — run any bd subcommand (--json is added automatically). Use only when no typed tool fits.

Slash command

/beads:wizard is a prompt (not a tool). When invoked, the agent is instructed to:

1. Refresh its knowledge of beads via Context7 (/gastownhall/beads) — falling back to https://gastownhall.github.io/beads/ if Context7 isn't available.
2. Inspect the current project (beads_doctor, beads_prime, beads_status).
3. Propose 2–4 concrete configuration options tailored to the user.
4. Apply only the option the user explicitly approves, using beads_* tools.
5. Return a brief structured report in the user's language.

The wizard never mutates anything without explicit consent.

Development

npm install
npm run check
npm run build
npm pack --dry-run