---

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.

$3

- 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

$3

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

Project-level (./opencode.json):
``json
{
"plugin": ["@simonwjackson/opencode-beads@latest"]
}
`

Global (~/.config/opencode/opencode.json):
`json
{
"plugin": ["@simonwjackson/opencode-beads@latest"]
}
`

---

Tools

$3

| 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 |

$3

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

$3

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

$3

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

$3

| 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 |

$3

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

$3

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

$3

| 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 |

$3

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

$3

| 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 |

$3

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

---

Usage

$3

`
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]
`

$3

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 │
└─────────────────────────────────────────────────────────────────┘
`

$3

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.

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

$3

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

$3

bd command not found
`bash


Verify beads is installed

which bd

Check if bd is in PATH

echo $PATH
`

No issues returned
`bash


Verify beads database exists

bd status

Initialize if needed

bd init
`

Permission errors
`bash


Check database directory permissions


ls -la .beads/
`

---

Contributing

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

`bash


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.

---