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

Enable the built-in plugin for 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.

Opencode

Add project instructions so Opencode knows how to invoke the CLI, then use natural language:

You: Import PROJ-123 from Jira
You: Fetch all issues for sprint-47
You: Sync my changes back to Jira

📖 Opencode Guide: See Opencode Guide for setup and workflow examples.

Other AI Tools

Any AI coding tool that can run shell commands can use jira-beads-sync. Add these commands to your project's instructions file:

Import a Jira issue:   jira-beads-sync quickstart <JIRA-KEY>
Fetch by label:        jira-beads-sync fetch-by-label <label>
Fetch by JQL:          jira-beads-sync fetch-jql '<jql>'
List issues:           bd list
Sync back to Jira:     jira-beads-sync sync

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.