embeadings 0.4.2

Local-first coordination review for Beads and Linear

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

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

python -m pip install \
  "https://github.com/DyrtyJax/embeadings/releases/download/v0.4.2/embeadings-0.4.2-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.2 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?

Evidence	Result	Boundary
Concurrent-worktree release gate	Recovered all 3 known exact-file collisions across 4 genuine active worktrees	One repository; not universal recall
Dogfooding	Found 2 real association/scope defects before v0.4.0	Demonstrates workflow value, not broad precision
Ruff scale surrogate	17/20 top-packet pairs were at least contextually useful across 8,143 public issues	Converted GitHub corpus; no native Beads graph or worktrees
Release validation	Full CI passed across Linux, macOS, Windows, Python 3.11 and 3.14; wheel/sdist checksums and provenance published	Supply-chain and test evidence, not semantic quality
Repeatability	Evaluation outputs were byte-stable and non-mutating	Determinism does not make a weak lead correct

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.

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.