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
• 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 Claude Code

Enable natural language issue management:

claude --plugin-dir /path/to/jira-beads-sync

Then simply ask Claude:

You: Import PROJ-123 from Jira
You: Show me all open issues
You: Mark PROJ-124 as in progress
You: Sync changes back to Jira

📖 Plugin Guide: See Plugin Guide for complete plugin documentation.

How It Works

This tool uses Protocol Buffers internally for type-safe data handling:

Jira (JSON) → Protobuf → beads (YAML) → Protobuf → Jira (JSON)
     ↓           ↓             ↓           ↓           ↓
  Fetch     Convert      Render      Detect      Update

Learn more: See CLAUDE.md for detailed architecture and CONTRIBUTING.md for development setup.

Contributing

Contributions welcome! See CONTRIBUTING.md for:

• Development setup
• Coding standards
• Testing guidelines
• Pull request process

Resources

• 📚 Getting Started Guide - New user walkthrough
• 🖥️ CLI Guide - Complete CLI reference
• 🤖 Plugin Guide - Claude Code plugin usage
• 💡 Examples - Real-world scenarios
• 🏗️ CLAUDE.md - Architecture for developers
• 🤝 Contributing - Development guidelines

Support

• Issues: https://github.com/conallob/jira-beads-sync/issues
• Discussions: https://github.com/conallob/jira-beads-sync/discussions
• Sponsor:

License

BSD-3-Clause - See LICENSE file for details.