opencode-beads

Comprehensive beads (bd) issue tracker integration for OpenCode

36 tools for managing issues, dependencies, epics, and more with the beads issue tracker.

Installation • Tools • Usage • Contributing

Overview

opencode-beads provides a comprehensive set of tools for the beads (bd) git-native issue tracker, giving AI assistants full control over issue management with first-class dependency support.

Key Features

• 36 Tools — Complete coverage of beads functionality
• Dependency Management — First-class support for issue dependencies and blocking detection
• Bulk Operations — Update, close, or reopen multiple issues at once
• Epic Support — Organize issues into epics for better project management
• AI Integration — Dedicated prime command for AI-optimized context
• JSON Output — Structured output for reliable parsing

Requirements

| Dependency | Version | Required | Notes | |------------|---------|----------|-------| | OpenCode | >=1.0.0 | Yes | Plugin host environment | | beads (bd) | 0.1.x | Yes | Tested version; must be available in PATH | | Bun | >=1.0.0 | Yes | Runtime environment | | TypeScript | >=5.0.0 | Dev only | For building from source |

Note: This plugin has only been tested with the JSONL backend. SQLite backend support is untested and may not work as expected.

Installation

Via OpenCode Config

Add the plugin to your OpenCode configuration — OpenCode handles installation automatically.

Project-level (./opencode.json):

{
  "plugin": ["@simonwjackson/opencode-beads@latest"]
}

Global (~/.config/opencode/opencode.json):

{
  "plugin": ["@simonwjackson/opencode-beads@latest"]
}

Tools

Core Issue Operations (7 tools)

| Tool | Description | |------|-------------| | bd_list | List issues with filters (status, label, priority, epic, assignee) | | bd_show | Show detailed issue information | | bd_create | Create new issues with dependencies | | bd_update | Update issue fields | | bd_close | Close one or more issues | | bd_reopen | Reopen closed issues | | bd_delete_issue | Delete issues and clean up references |

Workflow (2 tools)

| Tool | Description | |------|-------------| | bd_ready | Show issues ready to work on (no blocking deps) | | bd_blocked | Show issues blocked by dependencies |

Search & Query (3 tools)

| Tool | Description | |------|-------------| | bd_search | Text search across titles and bodies | | bd_count | Count issues matching filters | | bd_stale | Find issues not updated recently |

Comments (2 tools)

| Tool | Description | |------|-------------| | bd_comment | Add a comment to an issue | | bd_comments | View comments on an issue |

Labels (3 tools)

| Tool | Description | |------|-------------| | bd_label_add | Add a label to an issue | | bd_label_remove | Remove a label from an issue | | bd_labels | List all labels in the database |

Dependencies (3 tools)

| Tool | Description | |------|-------------| | bd_dep_add | Add a dependency between issues | | bd_dep_remove | Remove a dependency | | bd_deps | List dependencies for an issue |

Epics (3 tools)

| Tool | Description | |------|-------------| | bd_epic_create | Create a new epic | | bd_epics | List all epics | | bd_epic_show | Show epic details with child issues |

Database & Sync (6 tools)

| Tool | Description | |------|-------------| | bd_status | Show database overview with counts | | bd_stats | Show detailed statistics | | bd_sync | Synchronize with git remote | | bd_info | Show database and daemon information | | bd_validate | Run database health checks | | bd_doctor | Diagnose installation issues |

Templates (2 tools)

| Tool | Description | |------|-------------| | bd_templates | List available templates | | bd_create_from_template | Create issue from template |

Maintenance (4 tools)

| Tool | Description | |------|-------------| | bd_cleanup | Delete old closed issues | | bd_compact | Compact closed issues preserving git history | | bd_duplicates | Find potentially duplicate issues | | bd_repair_deps | Fix orphaned dependency references |

AI Integration (1 tool)

| Tool | Description | |------|-------------| | bd_prime | Output AI-optimized workflow context |

Usage

Basic Workflow

User: Show me issues that are ready to work on
AI: [Uses bd_ready tool]

User: Create a new issue for implementing dark mode
AI: [Uses bd_create with title "Implement dark mode"]

User: This issue depends on issue abc123
AI: [Uses bd_dep_add to create dependency]

User: Mark issue xyz789 as complete
AI: [Uses bd_close tool]

Dependency Management

The plugin excels at managing issue dependencies:

┌─────────────────────────────────────────────────────────────────┐
│                     Dependency Workflow                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  bd_ready → Find issues with no blockers                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  bd_blocked → Find issues waiting on dependencies               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  bd_deps → View dependency graph for any issue                  │
└─────────────────────────────────────────────────────────────────┘

Epic Organization

Group related issues into epics:

1. Create an epic: bd_epic_create
2. Assign issues to epic: bd_update with epic parameter
3. View epic progress: bd_epic_show

How It Works

All tools execute the bd CLI command with appropriate flags and return JSON output for reliable parsing.

// Example: bd_list implementation
const proc = Bun.spawn(["bd", "list", "--json", "--status", "open"])
const output = await new Response(proc.stdout).text()
return output

Error Handling

Tools return structured error messages when commands fail:

Error: Issue not found: abc123
Error: Dependency would create a cycle
Error: .envrc is blocked (run `direnv allow` to fix)

Troubleshooting

Common Issues

bd command not found

# Verify beads is installed
which bd

# Check if bd is in PATH
echo $PATH

No issues returned

# Verify beads database exists
bd status

# Initialize if needed
bd init

Permission errors

# Check database directory permissions
ls -la .beads/

Contributing

Contributions are welcome. Please read our contributing guidelines before submitting a pull request.

# Clone the repository
git clone https://github.com/simonwjackson/opencode-beads.git
cd opencode-beads

# Install dependencies
bun install

# Build
bun run build

# Type check
bun run typecheck

License

This project is licensed under the MIT License.

Built with

Made with care by @simonwjackson