jira-beads-sync

jira-beads-sync

Bridge Jira and beads: Import Jira issues locally, work with git-backed issue tracking, sync changes back to Jira.

jira-beads-sync synchronizes Jira issues with beads, a git-backed issue tracker. Work with Jira issues as YAML files in your repository, manage them with beads commands or Claude Code, then sync your changes back to Jira.

Perfect for developers who want to:

• Track Jira issues alongside code in version control
• Work with issues offline using beads
• Use natural language with Claude Code to manage issues
• Maintain bidirectional sync between Jira and local git repos

Quick Links

📚 New to jira-beads-sync? → Getting Started Guide

🎯 Use Cases:

• CLI User? → CLI Guide - Complete command reference
• Claude Code User? → Plugin Guide - Natural language workflows
• Opencode User? → Opencode Guide - Opencode integration
• Need Examples? → Real-World Examples - Practical scenarios

👩‍💻 For Developers:

• CLAUDE.md - Architecture and development guide
• CONTRIBUTING.md - Contribution guidelines

What Does It Do?

# Import a Jira issue with all its dependencies
jira-beads-sync quickstart PROJ-123

# Work locally with beads
bd list
bd show proj-123
bd update proj-123 --status in_progress

# Sync changes back to Jira
jira-beads-sync sync

Or use natural language with Claude Code:

You: Import PROJ-123 from Jira

Claude: [Imports issue and dependencies]
        ✓ Fetched 5 issue(s)
        Ready to work!

Key Features

• ✅ Bidirectional Sync: Import from Jira ↔ Work locally ↔ Push back to Jira
• ✅ Automatic Dependencies: Recursively fetches epics, stories, subtasks, and links
• ✅ Two Interfaces: CLI commands or natural language with Claude Code
• ✅ Preserves Structure: Maintains hierarchies, relationships, and metadata
• ✅ Git-Backed: Issues stored as YAML files in .beads/ directory
• ✅ Type-Safe: Built on Protocol Buffers for reliability

Installation

Homebrew (Recommended for macOS/Linux)

# Direct install (recommended)
brew install conallob/tap/jira-beads-sync

# Or tap first, then install
brew tap conallob/tap
brew install jira-beads-sync

From Binary

Download from the releases page or:

# macOS (Apple Silicon)
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Darwin_arm64.tar.gz
tar xzf jira-beads-sync_Darwin_arm64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/

# Linux (x86_64)
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Linux_x86_64.tar.gz
tar xzf jira-beads-sync_Linux_x86_64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/

From Source

go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest

More options: See Getting Started Guide for all installation methods including Docker, DEB, and RPM packages.

Quick Start

1. Configure Credentials

jira-beads-sync configure

You'll need a Jira API token from https://id.atlassian.com/manage-profile/security/api-tokens

2. Import a Jira Issue

jira-beads-sync quickstart PROJ-123

This fetches the issue and all its dependencies (subtasks, linked issues, parent issues).

3. Work Locally

bd list                              # List all issues
bd show proj-123                     # Show details
bd update proj-123 --status in_progress

4. Sync Back to Jira

jira-beads-sync sync

📖 Detailed Usage: See CLI Guide for all commands and options.

Using with AI Coding Tools

jira-beads-sync is a standard CLI binary that works with any AI coding assistant. Install it and configure Jira credentials once, then ask your AI tool to run commands on your behalf.

Claude Code