* Add Linear integration CLI with sync and status commands
- Add `bd linear sync` for bidirectional issue sync with Linear
- Add `bd linear status` to show configuration and sync state
- Stub pull/push functions pending GraphQL client (bd-b6b.2)
* Implement Linear GraphQL client with full sync support
- Add LinearClient with auth, fetch, create, update methods
- Implement pull/push operations with Beads type mapping
- Clean up redundant comments and remove unused code
* Add configurable data mapping and dependency sync for Linear
- Add LinearMappingConfig with configurable priority/state/label/relation maps
- Import parent-child and issue relations as Beads dependencies
- Support custom workflow states via linear.state_map.* config
* Add incremental sync support for Linear integration
- Add FetchIssuesSince() method using updatedAt filter in GraphQL
- Check linear.last_sync config to enable incremental pulls
- Track sync mode (incremental vs full) in LinearPullStats
* feat(linear): implement push updates for existing Linear issues
Add FetchIssueByIdentifier method to retrieve single issues by identifier
(e.g., "TEAM-123") for timestamp comparison during push.
Update doPushToLinear to:
- Fetch Linear issue to get internal ID and UpdatedAt timestamp
- Compare timestamps: only update if local is newer
- Build update payload with title, description, priority, and state
- Call UpdateIssue for issues where local has newer changes
Closes bd-b6b.5
* Implement Linear conflict resolution strategies
- Add true conflict detection by fetching Linear timestamps via API
- Implement --prefer-linear resolution (re-import from Linear)
- Implement timestamp-based resolution (newer wins as default)
- Fix linter issues: handle resp.Body.Close() and remove unused error return
* Add Linear integration tests and documentation
- Add comprehensive unit tests for Linear mapping (priority, state, labels, relations)
- Update docs/CONFIG.md with Linear configuration reference
- Add examples/linear-workflow guide for bidirectional sync
- Remove AI section header comments from tests
* Fix Linear GraphQL filter construction and improve test coverage
- Refactor filter handling to combine team ID into main filter object
- Add test for duplicate issue relation mapping
- Add HTTP round-trip helper for testing request payload validation
* Refactor Linear queries to use shared constant and add UUID validation
- Extract linearIssuesQuery to deduplicate FetchIssues/FetchIssuesSince
- Add linearMaxPageSize constant and UUID validation with regex
- Expand test coverage for new functionality
* Refactor Linear integration into internal/linear package
- Extract types, client, and mapping logic from cmd/bd/linear.go
- Create internal/linear/ package for better code organization
- Update tests to work with new package structure
* Add linear teams command to list available teams
- Add FetchTeams GraphQL query to Linear client
- Refactor config reading to support daemon mode
- Add tests for teams listing functionality
* Refactor Linear config to use getLinearConfig helper
- Consolidate config/env var lookup using getLinearConfig function
- Add LINEAR_TEAM_ID environment variable support
- Update error messages to include env var configuration options
* Add hash ID generation and improve Linear conflict detection
- Add configurable hash ID mode for Linear imports (matches bd/Jira)
- Improve conflict detection with content hash comparison
- Enhance conflict resolution with skip/force update tracking
* Fix test for updated doPushToLinear signature
- Add missing skipUpdateIDs parameter to test call
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.
The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.
Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks
Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When bd sync pushes from the sync-branch worktree, the pre-push hook
would detect uncommitted JSONL changes and suggest running bd sync -
which is circular since that's what the user is already doing.
Fix: Set BD_SYNC_IN_PROGRESS=1 environment variable when pushing from
worktree, and update pre-push hook to skip checks when this var is set.
Updated files:
- internal/syncbranch/worktree.go: Set env var on push command
- cmd/bd/templates/hooks/pre-push: Check for env var and exit early
- examples/git-hooks/pre-push: Same check
- .beads-hooks/pre-push: Same check
Fixes GH#409 - Documentation inconsistently referred to beads.jsonl
as the canonical filename when issues.jsonl has been the default
since v0.25.1 (bd-6xd).
Updated files:
- docs/ARCHITECTURE.md
- docs/CLI_REFERENCE.md
- docs/PROTECTED_BRANCHES.md
- docs/ADVANCED.md
- docs/GIT_INTEGRATION.md
- docs/MULTI_REPO_AGENTS.md
- docs/MULTI_REPO_MIGRATION.md
- docs/TROUBLESHOOTING.md
- examples/*/README.md
- skills/beads/references/CLI_REFERENCE.md
Note: beads.jsonl is still supported for backward compatibility.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two fixes to make pre-commit hook more resilient:
1. Check if beads is actually initialized (has db, config, or jsonl)
- Empty .beads directory no longer triggers sync attempt
- Handles case where .beads was removed from git but dir lingers
2. Make sync failure a warning instead of blocking error
- Beads issues shouldn't prevent code commits
- User can still run 'bd sync --flush-only' manually
Also synced examples/git-hooks/pre-commit with template (worktree handling).
Closes#483🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes GH#483 - The pre-commit hook was blocking commits when
`bd sync --flush-only` failed, even if the user had removed beads
from their branch. This made it impossible to commit on branches
that don't have beads configured.
Changes:
- Change "Error:" to "Warning:" in the message
- Remove `exit 1` so commits proceed even if flush fails
- Add comments explaining why we don't block commits
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)
* docs: update Go version requirement to 1.24+ across docs
* docs: fix broken links to docs/ in npm-package/README.md
* docs: fix QUICKSTART.md path reference in AGENTS.md
Reorganize the claude-code-skill into a publishable plugin that can be
installed through the beads-marketplace. Users can now reference the
'beads' skill right after installing the marketplace.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
Update `/bd-create` and `/bd-ready` to `/beads:create` and `/beads:ready`
in the claude-code-skill README. This was missed in PR #467.
Relates to #463🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replaces manual working directory save/restore patterns
with Go's built-in `t.Chdir()` helper across 23 test files.
The manual pattern involved calling `os.Getwd()` to save
the original directory, using `defer os.Chdir(origWd)` for
restoration, and manually handling errors during directory
changes. This boilerplate has been replaced with single
`t.Chdir(path)` calls that handle cleanup automatically.
The `t.Chdir()` method automatically restores the working
directory when the test completes, eliminating the need for
manual defer statements and error handling.
Total:
~75 instances replaced (assuming Claude's math is right)
Co-authored-by: Claude <noreply@anthropic.com>
- Fix DEPENDENCIES.md: correct parent-child syntax (child depends on parent)
- Update bd show: display Children instead of Blocks for parent-child deps
- Group dependents by type with distinct labels
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#441. The JIRA REST API v2 /search endpoint has been deprecated
and returns HTTP 410 Gone. Migrate to API v3 /search/jql endpoint.
Changes:
- Update API endpoint from /rest/api/2/search to /rest/api/3/search/jql
- Add URL encoding for JQL query parameter (Python 3.14 compatibility)
- Add reference to Atlassian migration guide
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add a Python script to push bd issues to Jira.
Features:
- Create new Jira issues from bd issues without external_ref
- Update existing Jira issues matched by external_ref
- Handle Jira workflow transitions for status changes
- Reverse field mappings (bd -> Jira) via config
- Dry-run mode for previewing changes
- Auto-update external_ref after creation (--update-refs)
Also updates README to document bidirectional sync workflow.
Closes bd-93d
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add a Python script to import Jira issues into beads JSONL format.
Features:
- Fetch issues from Jira Cloud or Server/Data Center REST API
- JQL query support for flexible filtering
- Configurable field mappings via bd config
- Hash-based or sequential ID generation
- Issue links converted to dependencies
- external_ref set for re-sync capability
Configuration options:
- jira.url, jira.project, jira.api_token
- jira.status_map.*, jira.type_map.*, jira.priority_map.*
Closes bd-tjn
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Change comments from sync.branch to sync-branch for consistency
- Add head -1 to handle malformed YAML with duplicate keys
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Previously sync.branch was stored in the database via bd config set.
Now it is in config.yaml (version controlled, shared across clones):
sync-branch: "beads-sync"
Changes:
- Add sync-branch to .beads/config.yaml
- Update syncbranch.Get() to check config.yaml before database
- Add syncbranch.GetFromYAML() and IsConfigured() for fast checks
- Update hooks to read sync-branch from config.yaml directly
- Update bd doctor to check config.yaml instead of database
- Remove auto-fix (config.yaml changes should be committed)
Precedence: BEADS_SYNC_BRANCH env > config.yaml > database (legacy)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When sync.branch is configured, .beads changes are committed to a
separate branch via worktree rather than the current branch. Updated
both hooks to detect this configuration and skip the uncommitted
.beads check in that scenario.
Changes:
- pre-push: Skip uncommitted .beads check when sync.branch is set
- pre-commit: Skip flush and auto-staging when sync.branch is set
- Both: Use --json output for reliable config value detection
- Bump version to 0.22.2
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds worktree detection to post-checkout hooks. When entering a git
worktree, displays a warning explaining that daemon mode has limitations
with worktrees and recommends using BEADS_NO_DAEMON=1.
Detection uses `git rev-parse --git-dir` vs `--git-common-dir` comparison
to identify worktree checkouts.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: maphew <maphew@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Two fixes to prevent git pull --rebase from failing:
1. Skip hook execution during rebase operations by detecting
.git/rebase-merge or .git/rebase-apply directories
2. Use --no-git-history flag to prevent git-history-backfill
from writing to deletions.jsonl during imports
The root cause was that post-checkout hooks were running during
rebase, triggering the git-history-backfill which appends to
deletions.jsonl. This created uncommitted changes that blocked
the rebase from continuing.
Bump hooks version to 0.26.0.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update examples/claude-code-skill/references/CLI_REFERENCE.md to match
docs/CLI_REFERENCE.md. The skill version was ~17% smaller and missing
newer sections like Global Flags, Sandbox Mode, Orphan Handling, etc.
Fixes#401🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The pre-commit and pre-push hooks were only staging beads.jsonl and
issues.jsonl, but not deletions.jsonl. This caused deletions.jsonl
to remain untracked after bd cleanup or bd delete operations.
Updated all hook locations:
- cmd/bd/templates/hooks/pre-commit
- cmd/bd/templates/hooks/pre-push
- examples/git-hooks/pre-commit
- examples/git-hooks/pre-push
- .beads-hooks/pre-commit
- .beads-hooks/pre-push
Users with existing hooks should run: bd hooks install
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When using --id-mode hash, the script now tracks generated IDs and
retries with increasing nonce (0-9) then increasing length (up to 8)
if a collision is detected within the same import batch.
This matches the collision handling behavior in the Go implementation
(internal/storage/sqlite/ids.go).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add --check-health flag for quick, silent health checks (exit 0 on success)
- Check version mismatch (CLI vs database), sync.branch config, outdated hooks
- Add hints.doctor config option to suppress doctor hints globally
- Update post-merge/post-checkout hooks to call bd doctor --check-health
- Suggest running bd doctor in upgrade notification
- Modernize post-checkout hook (bash→sh, use bd sync instead of bd import)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds --id-mode flag to gh2jsonl.py with support for both sequential
and hash-based IDs, matching the algorithm in internal/storage/sqlite/ids.go.
New features:
- encode_base36() function for base36 encoding
- generate_hash_id() matching Go implementation (SHA256 + base36)
- --id-mode {sequential|hash} CLI flag (default: sequential)
- --hash-length {3,4,5,6,7,8} for configurable hash length (default: 6)
Hash IDs are deterministic and content-based, using title, description,
creator, and timestamp. Sequential mode remains the default for backward
compatibility.
Examples:
python gh2jsonl.py --repo owner/repo --id-mode hash | bd import
python gh2jsonl.py --file issues.json --id-mode hash --hash-length 4
Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.
## Changes
### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239
### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
- Auto-detects bd version changes via .beads/metadata.json
- Shows bd info --whats-new when upgrade detected
- Auto-updates outdated git hooks
- Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
- Claude Code, GitHub Copilot, Cursor integration patterns
- Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section
## Impact
Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features
Works today with zero bd code changes required!
Related: #239🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The pre-push hook now provides better guidance when beads JSONL has
uncommitted changes:
- Interactive terminals: Prompts to auto-run 'bd sync' (y/N)
- Non-interactive/CI: Shows 'bd sync' command to run
- Fallback: Manual git commands if bd not available
This addresses the UX issue where users weren't sure they should
run 'bd sync' instead of manual git commands.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes display bug where P0 issues were shown as P2 due to JavaScript treating 0 as falsy. Also adds P0 to the priority filter dropdown.
Changes:
- Replace || with ?? operator for priority defaults in monitor UI
- Add P0 option to priority filter selector
Co-authored-by: Zack Rosen <zjrosen@users.noreply.github.com>
- Fix existing tests to work with new installHooks signature
- Add TestInstallHooksShared to verify shared hooks functionality
- Update git-hooks README with comprehensive --shared documentation
- Document benefits, use cases, and workflow for shared hooks
Fixes status filter bug, adds multi-select priority filter, find-as-you-type search, and interactive stats cards. Includes visual improvements for hover effects and alignment.
Co-authored-by: maphew <matt.wilkie@yukon.ca>
Fixes#340
Created AGENT_INSTRUCTIONS.md to house detailed operational instructions,
reducing AGENTS.md from 963 to 626 lines (~35% reduction).
Changes:
- New AGENT_INSTRUCTIONS.md with development, testing, and release procedures
- AGENTS.md now serves as quick overview with references to detailed docs
- Updated README.md link to "Landing the Plane" section
- Fixed broken team-workflow README links
Benefits:
- Prevents context pollution when multiple tools add instructions
- Better separation: quick reference vs detailed operations
- Enables tool-specific instruction files
- Maintains all content, just reorganized
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
monitor-webui fails to connect to the bd daemon because it calculates the socket path incorrectly. It expects beads.db.sock in a nested .beads directory, whereas the daemon listens on bd.sock in the .beads directory.
Updated `getSocketPath` function to:
- Check if dbPath directory is already .beads.
- Use bd.sock as the socket name instead of [dbName].sock.
- Handle both nested and non-nested cases correctly.
Previously the hook redirected stderr to /dev/null, hiding useful error
messages like 'Git conflict markers detected'. Users only saw a generic
warning with no indication of the root cause.
Now captures and displays the actual error output, making it immediately
clear what went wrong (e.g., merge conflicts in JSONL).
Fixes bd-nszi
Amp-Thread-ID: https://ampcode.com/threads/T-6231e968-2c06-44ad-855d-bb5fafe452f6
Co-authored-by: Amp <amp@ampcode.com>
- Add AGENT_MAIL_QUICKSTART.md: 5-minute setup guide
- Add examples/python-agent/AGENT_MAIL_EXAMPLE.md: working code examples
- Add examples/python-agent/agent_with_mail.py: runnable multi-agent demo
- Update README.md: add Agent Mail to features and docs index
- Update AGENTS.md: enhance with quickstart/example references
- Update examples README: add Agent Mail example to index
Amp-Thread-ID: https://ampcode.com/threads/T-5d5e711d-7b5f-42ca-b75a-5b6cd843ad98
Co-authored-by: Amp <amp@ampcode.com>
