opencode-beads

Custom OpenCode integration for Beads-first task workflow.

What is included

Tools

• beads_prime
• beads_init
• beads_overview
• beads_list
• beads_show
• beads_graph
• beads_create
• beads_update
• beads_comment_add
• beads_comments_list
• beads_task_report
• beads_doctor

Slash commands

• /beads-prime
• /beads-init
• /beads-overview
• /beads-list
• /beads-show
• /beads-graph
• /beads-create
• /beads-update
• /beads-comment
• /beads-comments
• /beads-analyze
• /beads-doctor

Analyzer layer

• Subagent: .opencode/agents/beads-analyst.md
• Skill: .opencode/skills/beads-task-analyzer/SKILL.md
• Composite tool: beads_task_report
• Command: /beads-analyze <issue-id>

Tool usage reference

Core read tool:

• beads_list({ scope: "tasks" | "epics" | "all", ...filters }) - regular issue list.
• beads_list({ queue: "ready" | "blocked", ...filters }) - queue view (dependency-aware ready/blocked).

Core write tool:

• beads_update({ id, status }) - status transitions.
• beads_update({ id, parent }) - move issue under epic (parent: "" clears parent).
• beads_update({ id, add_labels | remove_labels | set_labels }) - label updates.
• beads_update({ id, status: "closed", reason }) - close with reason.

Minimal lifecycle via tools:

beads_create({ title: "Implement feature X", type: "task" })
beads_update({ id: "<issue-id>", status: "in_progress" })
beads_comment_add({ id: "<issue-id>", message: "[progress] implemented core path" })
beads_update({ id: "<issue-id>", status: "closed", reason: "implemented and validated" })

Runtime installation model

beads_init does Beads bootstrap and then runs runtime setup in safe missing-only mode.

When launched without arguments, /beads-init uses sane defaults (daemon off, hooks chain, runtime local) and runs immediately.

Available flags:

• --prefix <name> — issue prefix for bd init
• --daemon auto|on|off — daemon policy (default off)
• --hooks auto|chain|shared|skip — hooks policy (default chain)
• --runtime-target local|global — where to install runtime assets (default local)
• --sync-branch <name> — sync branch name
• --team / --contributor / --stealth — pass corresponding flag to bd init
• --skip-hooks — skip hook installation
• --force — force re-initialization and bypass linked-worktree safety guard
• --dry-run — report actions without executing

Worktree safety rule:

• /beads-init checks whether current directory is a linked git worktree
• if linked worktree is detected, init is blocked by default to avoid accidental .beads loss with worktree removal
• recommended flow: run init from main worktree root
• override is possible only with explicit --force

Managed runtime assets:

• agent: .opencode/agents/beads-analyst.md
• skills: .opencode/skills/beads-task-analyzer/SKILL.md
• slash commands are loaded from plugin package assets/commands (not synced into .opencode/commands)

Important behavior:

• Existing files are not overwritten by beads_init.
• Overwrite is possible only via explicit /beads-doctor --fix --force.
• Sync writes a lockfile with source/installed hashes (.opencode/beads/runtime-assets.lock.json for local target, beads/runtime-assets.lock.json for global target) for deterministic drift checks.
• Obsolete previously-managed runtime files are removed automatically during full sync.

Local vs global runtime target

You choose where runtime files are installed:

• local (default): install into current repo (.opencode/...), so this project uses its own agent/skill templates
• global: install into ~/.config/opencode/..., so one shared runtime is reused across repositories

How to choose:

• choose local for team/shared repos or when you want project-pinned behavior
• choose global for personal setup when you want one runtime for all repos

Important: runtime target affects only synced OpenCode runtime assets (.opencode/...) such as agents/skills. It does not move Beads issue storage (.beads database).

Beads storage model in worktrees:

• default: one shared .beads source of truth in the main repository
• worktrees read/write the same issue storage via this shared location
• advanced override is possible with BEADS_DB=/custom/path/beads.db (manual env-level setup)

Use with init:

/beads-init --runtime-target local
/beads-init --runtime-target global

Doctor command

/beads-doctor checks Beads and runtime presence. With --fix, it also repairs missing assets.

• Without --fix: diagnose only (report warnings and suggested fixes)
• With --fix: diagnose AND install missing runtime assets
• With --fix --force: overwrite existing managed files to plugin defaults
• With --fix --dry-run: report what would be fixed without writing

Examples:

/beads-doctor
/beads-doctor --target global --scope skills
/beads-doctor --fix
/beads-doctor --fix --force --target local
/beads-doctor --fix --dry-run

Setup (local development)

1. Install dependencies:

bun install

2. Type-check:

bun run check

3. Restart OpenCode so it reloads .opencode/.

Quick workflow

1. /beads-init
2. /beads-overview
3. /beads-list --scope tasks
4. /beads-show <issue-id>
5. /beads-update <issue-id> --status in_progress
6. /beads-analyze <issue-id> (optional, recommended for non-trivial tasks)
7. /beads-comment <issue-id> "[progress] implemented core path"
8. /beads-update <issue-id> --status closed --reason "implemented and validated"

Command surface (compact)

• Primary read commands: /beads-overview, /beads-list, /beads-show, /beads-graph
• Primary write commands: /beads-create, /beads-update, /beads-comment
• Analysis and setup: /beads-analyze, /beads-init, /beads-doctor

File protection behavior

beads_init protects by default:

• AGENTS.md
• .github/copilot-instructions.md

If bd init modifies or creates these unexpectedly, beads_init restores/removes them and reports this in file_protection.

Allow writes intentionally:

/beads-init --allow-agents-write

Daemon behavior and expectations

beads_init defaults daemon to off. Override with --daemon on or --daemon auto.

Why daemon is off by default:

• opencode-beads tool wrappers execute bd with direct mode safeguards (--no-daemon and BEADS_NO_DAEMON=1) for deterministic behavior
• daemon mode with parallel worktrees can cause branch-context confusion
• direct mode is safer for predictable branch isolation

If you need daemon mode (e.g. for editor integration), override explicitly:

/beads-init --daemon on

Daemon settings mainly affect raw bd usage and future policy changes.

Notes

• Tools run with worktree-safe defaults (--no-daemon, BEADS_NO_DAEMON=1).
• Prefer slash commands and custom tools over raw bd in normal flow.