emBEADings

Find engineering work that may trip over the same code—without changing the tracker or sending issue text to an embedding API.

emBEADings is a read-only coordination CLI for Beads and Linear. It combines typed tracker relationships, local semantic retrieval, explicit code pointers, and genuine Git worktree changes into a bounded, deterministic review queue.

Dependencies answer “what blocks this?” emBEADings asks “what else should I inspect before these changes merge?” It provides evidence, not an automatic verdict.

Status: v0.4 technical preview. The CLI and GitHub release are public; the bundled Codex and Claude Code plugin is still a local developer preview.

Quick start

Python 3.11 or later is required. The default Beads source also requires an installed bd CLI.

pipx install embeadings
# or: uv tool install embeadings

# Check the environment without loading issue text
embead doctor

# Produce a bounded coordination packet
embead triage

# Find active work touching the same files or modules
embead collisions

# Inspect semantic neighbors for one record
embead neighbors ISSUE_ID --include-closed

# Find the stragglers: similar records with no structural link
embead neighbors ISSUE_ID --orphans-only

Without pipx or uv, the standard library is enough:

python3 -m venv .venv
. .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install embeadings

For an immutable GitHub fallback, install the verified release wheel directly:

python -m pip install \
  "https://github.com/DyrtyJax/embeadings/releases/download/v0.4.3/embeadings-0.4.3-py3-none-any.whl"

The first semantic command downloads the pinned minishlab/potion-base-8M model. Embedding happens locally. collisions does not load an embedding model.

Release assets include a source archive and SHA256SUMS. See the v0.4.3 release for versioned artifacts and checksums.

What a lead looks like

This shortened example is derived from the committed synthetic collision fixture:

{
  "issue_id": "demo-1",
  "related_issue_id": "demo-2",
  "kind": "exact-file",
  "confidence": "observed",
  "shared_paths": ["src/cache/index.py"],
  "evidence_sources": ["active-worktree-diff"],
  "what_to_verify": "Verify whether concurrent work will modify the shared file paths before implementation or merge."
}

The full report also records repository provenance, revision relation, hub suppression, warnings, and the read-only policy. It contains pointers rather than source snippets. See examples/collisions.json and the example guide.

Why trust it?

Read the dogfood release-gate story, aggregate v0.4.0 worktree gate, Ruff scale review, and the research index for methods, failure patterns, and limitations.

How it works

Beads or one Linear team
        │
        ├── typed relationships and lifecycle
        ├── explicit paths and observed worktree changes
        └── local whole-record and field-level embeddings
                              │
                              ▼
                   bounded candidate union
                              │
                              ▼
                evidence receipts + review packet

triage is the opinionated front door. It admits at most 20 semantic candidates by default, includes code-surface analysis when genuine local Git evidence exists, and writes a complete audit report to external user state. Use sweep for experimental policy controls and neighbors for one-record inspection. The default is a reviewer-capacity budget, not corpus coverage; see the review-budget decision.

For triage, sweep, and batch, use --output-dir DIRECTORY when you want the complete JSON, Markdown, and per-batch artifact set. Use --output report.json or --output report.md for one primary report file; the extension chooses the file format independently of --json stdout. Any other --output PATH remains a backward-compatible directory spelling. neighbors and collisions always treat --output as one atomic report file.

collisions reviews open, in_progress, and blocked work by default. It associates Git worktrees when a branch contains a full Bead ID or unambiguous bead-N suffix. Explicitly map an otherwise unassociated worktree with:

embead collisions --worktree-map embead-42=../feature-worktree

Never fabricate a mapping: observed evidence must describe genuine active implementation work. Shared paths are coordination evidence, not proof that two tasks conflict.

Linear

Create a personal API key in Linear's Security & access settings and load it without placing the value directly in a shell-history entry:

LINEAR_API_KEY="$(python -c 'import getpass; print(getpass.getpass("Linear API key: "))')"
export LINEAR_API_KEY

embead --source linear --linear-team ENG triage
embead --source linear --linear-team ENG collisions

LINEAR_ACCESS_TOKEN accepts an OAuth token instead; set only one credential. The CLI queries one selected team through Linear GraphQL and does not reuse credentials held by an MCP or agent host. See the Linear adapter contract.

Privacy and data boundary

• Tracker adapters contain no mutation operations.
• The default model embeds issue text locally; issue text is not sent to Hugging Face.
• Linear mode sends tracker queries only to Linear itself.
• Models and vectors use the platform user cache; reports use the platform user state directory.
• Neither cache nor reports are written into the analyzed repository by default.
• Collision reports contain code pointers, not source snippets.
• A human or coordinator must verify every lead before changing tracker or source state.

The first model download is network activity. Prepare it before loading private issues when evaluating under OS-level network denial. See the safe offline evaluation guide.

Good fit / poor fit

emBEADings is most useful when a tracker is too large for repeated full-context review, several people or agents work concurrently, and the team values a reproducible offline shortlist.

It is less useful for a small tracker that one reviewer can read directly, repositories without meaningful tracker-to-code evidence, or teams seeking automatic issue mutation, orchestration, a dashboard, or a general memory system. Typed dependencies remain tracker truth; semantics complement them rather than re-deriving authority.

Development

Every clone or Git worktree must own its virtual environment:

python3 scripts/worktree_env.py
. .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python scripts/validate.py

The bootstrap refuses to reuse an active environment from another checkout. Validation checks the editable embead import target before formatting, lint, tests, and release checks. Read CONTRIBUTING.md before submitting fixtures or reports; private tracker content must never be committed.

Agent plugin preview

plugins/embeadings packages triage, collisions, and evaluate skills for local Codex and Claude Code development. It delegates to the installed CLI, forces schema-v1 JSON, and verifies the read-only policy. It is not yet a marketplace release and grants no tracker-write authority.

Documentation

• Documentation index
• CLI and product specification
• Consumer and schema contract
• Performance and scale evaluation
• Research and evaluation ledger
• Versioned JSON Schemas and synthetic examples

Principles

• Read-only means read-only. Analysis never closes, edits, labels, or reprioritizes work.
• The tracker remains authoritative. Structure and lifecycle stay tracker data.
• Local-first and private. The default semantic provider sends no issue content to a network API.
• Bounded and auditable. A stable receipt explains what entered or was omitted from the queue.
• Agent-neutral. Core analysis does not depend on Codex, Claude Code, Cursor, or another runtime.

MIT licensed. emBEADings is not affiliated with Beads or Linear.