beads-workflows

Workflow engine + TypeScript SDK for the beads issue tracker.

Installation

bun add beads-workflows

Quick Start

import { Beads } from 'beads-workflows'

const beads = await Beads()

// List ready issues
const ready = await beads.issues.ready()

// Create and close issues
await beads.issues.create({ title: 'New task', type: 'task' })
await beads.issues.close('bw-123')

Event Handlers

Drop handler files in .beads/ - they execute when issues change:

// .beads/on.issue.created.ts
export default async ({ issue, beads }) => {
  console.log(`New issue: ${issue.title}`)
}

// .beads/on.issue.closed.ts
export default async ({ issue, beads }) => {
  // Auto-close epic when all children done
  for (const epicId of issue.blocks) {
    const progress = await beads.epics.progress(epicId)
    if (progress.percentage === 100) {
      await beads.issues.close(epicId)
    }
  }
}

Scheduled Handlers

// .beads/every.hour.ts - runs hourly
export default async ({ issues }) => {
  const stale = issues.filter(i => /* stale check */)
  console.log(`Found ${stale.length} stale issues`)
}

// .beads/every.day.ts - runs daily
// .beads/every.week.ts - runs weekly

Or use the every() API for custom crons:

import { every } from 'beads-workflows'

every('0 9 * * 1-5', async ({ issues }) => {
  console.log('Good morning!')
})

CLI

# Watch mode (daemon)
beads-workflows run

# Single pass
beads-workflows run --once

# View execution history
beads-workflows list
beads-workflows list --failed

# Retry failed
beads-workflows retry bw-123 closed
beads-workflows retry --all-failed

GitHub Action

Runs workflows on push, schedule, or manual trigger:

name: beads-workflows
on:
  push:
    branches: [main]
    paths: ['.beads/issues.jsonl']
  schedule:
    - cron: '0 * * * *'   # hourly
    - cron: '0 0 * * *'   # daily

See GitHub Action docs for full setup.

APIs

| API | Description | |-----|-------------| | Beads() | Main factory with issues/epics access | | issues.list() | Query issues with filters | | issues.ready() | Issues with no blockers | | issues.create() | Create new issues | | epics.progress() | Epic completion tracking | | Workflows() | Execution history and retry | | diff() | Change detection between commits | | every() | Register scheduled handlers |

Documentation

Full documentation in docs/:

• Getting Started
• Issues API
• Epics API
• Event Handlers
• Scheduled Handlers
• CLI Reference
• GitHub Action

License

MIT