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_runtime_setup
• 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-runtime-setup
• /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 runs a staged wizard (2-3 blocks) and executes init immediately after the final block.

Question blocks:

• block 1 (general): scenario/profile, runtime sync, runtime target, execution mode
• block 2 (usage experience): daemon/hooks/sync policy and key safety toggles
• block 3 (fine tuning): prefix/custom branch and advanced overrides

Dependency rules are applied between blocks:

• next block questions depend on prior answers
• conflicting options are hidden or auto-resolved with explanation
• profile-locked choices (for example worktree -> daemon off) skip irrelevant questions
• final output is a practical setup report (what configured, why, what enabled/disabled, and day-to-day usage)

Worktree safety rule in init:

• preflight runs before wizard questions
• /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

If arguments are plain text hints (for example /beads-init на русском) and not CLI flags, the same staged wizard flow is used.

Managed runtime assets:

• commands: .opencode/commands/beads-*.md
• agent: .opencode/agents/beads-analyst.md
• skills: .opencode/skills/beads-task-analyzer/SKILL.md

Important behavior:

• Existing files are not overwritten by beads_init.
• Overwrite is possible only via explicit /beads-runtime-setup --force.

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 command/agent 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 OpenCode runtime assets (.opencode/...). 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 solo --runtime-target local
/beads-init solo --runtime-target global

Runtime repair/update command

/beads-runtime-setup installs missing files or (with force) rewrites managed files.

Examples:

/beads-runtime-setup --target local
/beads-runtime-setup --target global --scope skills
/beads-runtime-setup --target local --scope skills --force
/beads-runtime-setup --dry-run

Doctor command

/beads-doctor checks Beads and runtime presence.

• Missing runtime assets are reported as warnings.
• Existing modified files are not treated as errors.

Examples:

/beads-doctor
/beads-doctor --target global
/beads-doctor --scope skills

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, /beads-runtime-setup

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 sets daemon.auto_start based on profile (or explicit --daemon):

• team: daemon on by default
• worktree: daemon off by default (to reduce cross-worktree confusion)
• solo, contributor, stealth: conservative defaults

Why worktree defaults to daemon off:

• Beads worktrees share one central .beads source of truth
• daemon mode with parallel worktrees can cause branch-context confusion
• direct mode is safer for predictable branch isolation

VSCode/editor integration note:

• some editor workflows are better with daemon enabled
• if you need this, you can override explicitly (for example /beads-init worktree --daemon on)
• use with care when multiple worktrees are active in parallel

Important: opencode-beads tool wrappers execute bd with direct mode safeguards (--no-daemon and BEADS_NO_DAEMON=1) for deterministic worktree behavior. So 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.