npm package: @simonwjackson/opencode-beads
Description: OpenCode plugin for beads (bd) issue tracker integration
Author: simonwjackson
Latest version: 2025.1217.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<div align="center">

# opencode-beads

**Comprehensive beads (bd) issue tracker integration for OpenCode**

[![npm version](https://img.shields.io/npm/v/@simonwjackson/opencode-beads?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@simonwjackson/opencode-beads)
[![npm downloads](https://img.shields.io/npm/dm/@simonwjackson/opencode-beads?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@simonwjackson/opencode-beads)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.0-f9f1e1?style=flat-square&logo=bun&logoColor=black)](https://bun.sh/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-8B5CF6?style=flat-square)](https://opencode.ai/)

---

*36 tools for managing issues, dependencies, epics, and more with the [beads](https://github.com/steveyegge/beads) issue tracker.*

[Installation](#installation) •
[Tools](#tools) •
[Usage](#usage) •
[Contributing](#contributing)

![Demo](demo.gif)

</div>

---

## 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](https://opencode.ai/) | `>=1.0.0` | Yes | Plugin host environment |
| [beads (bd)](https://github.com/steveyegge/beads) | `0.1.x` | Yes | Tested version; must be available in PATH |
| [Bun](https://bun.sh/) | `>=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`):
```json
{
  "plugin": ["@simonwjackson/opencode-beads@latest"]
}
```

**Global** (`~/.config/opencode/opencode.json`):
```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.

```typescript
// 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**
```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](LICENSE).

---

<div align="center">

**Built with**

[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-f9f1e1?style=for-the-badge&logo=bun&logoColor=black)](https://bun.sh/)

---

Made with care by [@simonwjackson](https://github.com/simonwjackson)

</div>