# emBEADings: find duplicate and related issues in Beads and Linear

emBEADings reads your [Beads](https://github.com/gastownhall/beads) tracker (or one Linear team) and finds the issues that belong together. It only reads: it never changes a status, adds a link or posts a comment, and issue text is embedded on your own machine.

Install: `pipx install embeadings` (or `pip install embeadings`, Python 3.11+). Source: https://github.com/CantrellJax/embeadings (MIT). Package: https://pypi.org/project/embeadings/

## What it finds

- **Issues that belong together but have no link.** `embead neighbors ISSUE --orphans-only` lists the issues most like one issue that the tracker does not link to it. `embead triage` gives a short, bounded list of such pairs across the whole tracker.
- **Open issues a merge already did.** `embead superseded --since 2026-10-01` reads the merged changes from git (or a list of pull requests), lists the open issues a change names by ID, and ranks the rest against each squashed commit.
- **Work about to collide.** `embead collisions` finds active issues that touch the same files, from explicit references or real git worktree diffs.
- **Prose that says "duplicate of" with no link.** `embead mentions` finds issues whose notes say "folded into", "duplicate of" or "superseded by" another, where no typed link backs it.
- **Duplicates before they are filed.** `embead match --title "..."` finds the existing issues a new one would duplicate, including closed ones.
- **A whole sprint at once.** `embead neighbors --ids-file sprint.txt --format table` prints one line per lead across many seeds, with its best seed, assignee and guards (owner labels, in-progress work).

Every report is advisory evidence with a versioned JSON schema (`embead schema REPORT_TYPE`), never a verdict.

## What the page shows

The page is a scroll story told with beads. Each bead is an invented issue at Apogee Uplink, a fictional company that writes transmission software for rockets: colour is its epic (tongue-in-cheek initiatives like "Operation Please Don't Explode" and "Project Can You Hear Me Now"), material is status (clear glass for open, lit from inside for in progress, matte for blocked, frosted for closed).

1. A pile of beads rests on the word emBEADings.
2. Sorted: scrolling strings the beads onto one cord per topic, the way emBEADings groups similar issues.
3. Tied: three beads hang off their cord with no link. A pink arc ties each to the issue it matches, 0.91, 0.87 and 0.84 alike.
4. Shipped: merged pull request #212 carries off the three issues it already did. An issue labelled owner-run stays put.

Below the story, visitors drag merged pull request cards onto a table of beads; each card strings up the issues it finished.

## Who made it

Jackson Cantrell (https://jacksoncantrell.com, https://github.com/CantrellJax, https://linkedin.com/in/jacksoncantrell) makes products, and these days makes them alongside a lot of AI agents. emBEADings is the tool he built to keep his own Beads tracker honest. Issues, ideas and pull requests are welcome: https://github.com/CantrellJax/embeadings/issues/new

## Guides

- [Find duplicate issues in Beads, even in different words](https://embeadings.jacksoncantrell.com/beads-duplicate-issues/)
- [Clean up a bloated Linear backlog](https://embeadings.jacksoncantrell.com/linear-backlog-cleanup/)
- [Which open issues did my merged pull requests already fix?](https://embeadings.jacksoncantrell.com/close-issues-after-merge/)
- [Teach your agents to look before they file](https://embeadings.jacksoncantrell.com/for-agents/) (raw instructions: https://embeadings.jacksoncantrell.com/agents.md)

emBEADings is an independent tool listed in the Beads community tools: https://beads.gascity.com/community-tools