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:
👩💻 For Developers:
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
