beadloom 1.4.0

Context Oracle + Doc Sync Engine for AI-assisted development

Beadloom

Read this in other languages: Русский

Your architecture shouldn't live in one person's head.

---

Beadloom is a knowledge management tool for codebases. It turns scattered architecture knowledge into an explicit, queryable graph that lives in your Git repository — accessible to both humans and AI agents.

IDE finds code. Beadloom tells you what that code means in the context of your system.

Platforms: macOS, Linux, Windows  |  Python: 3.10+

Why Beadloom?

Large codebases have a knowledge problem that code search alone doesn't solve:

• "Only two people understand how this system works." Architecture knowledge lives in heads, not in the repo. When those people leave, the knowledge goes with them.
• "The docs are lying." Documentation goes stale within weeks. Nobody notices until an agent or a new hire builds on top of outdated specs.
• "AI agents reinvent context every session." Each agent run starts from scratch — grepping, reading READMEs, guessing which files matter. Most of the context window burns on orientation, not on actual work.

Beadloom solves this with two primitives:

1. Context Oracle — an architecture graph (YAML in Git) that maps your domains, features, services, and their relationships. Query any node and get a deterministic, compact context bundle in <20ms. Same query, same result, every time.

2. Doc Sync Engine — tracks which docs correspond to which code. Detects stale documentation on every commit. No more "the spec says X but the code does Y".

Deterministic context, not probabilistic guessing

IDE indexers use semantic search — an LLM decides what's relevant. This works for "find similar code", but fails for "explain this feature in the context of the whole system".

Beadloom uses deterministic graph traversal: your team defines the architecture graph, and BFS produces the same context bundle every time. The graph is YAML in Git — reviewable in PRs, auditable, version-controlled.

	Semantic search (IDE)	Beadloom
Answers	"Where is this class?"	"What is this feature and how does it fit?"
Method	Embeddings + LLM ranking	Explicit graph + BFS traversal
Result	Probabilistic file list	Deterministic context bundle
Docs	Doesn't track freshness	Catches stale docs on every commit
Knowledge	Dies with the session	Lives in Git, survives team changes

Beadloom doesn't replace your IDE. It gives your IDE — and your agents — the architectural context they can't infer from code alone.

Install

uv tool install beadloom        # recommended
pipx install beadloom            # alternative

Quick start

# 1. Scan your codebase and generate an architecture graph
beadloom init --bootstrap

# 2. Review the generated graph (edit domains, rename nodes, add edges)
vi .beadloom/_graph/services.yml

# 3. Build the index and start using it
beadloom reindex
beadloom ctx AUTH-001              # get context for a feature
beadloom sync-check                # check if docs are up to date

No documentation required to start — Beadloom bootstraps from code structure alone.

Connect AI agents via MCP

beadloom setup-mcp                 # creates .mcp.json automatically

Agents call get_context("AUTH-001") and receive a ready-made bundle — zero search tokens:

{
  "mcpServers": {
    "beadloom": {
      "command": "beadloom",
      "args": ["mcp-serve"]
    }
  }
}

Works with Claude Code, Cursor, and any MCP-compatible tool.

Who is it for?

Tech Lead / Architect — You want architecture knowledge to be explicit, versionable, and survive team rotation. Beadloom makes the implicit explicit: domains, features, services, dependencies — all in YAML, all in Git.

Platform / DevEx Engineer — You build tooling for the team. Beadloom gives your agents structured context out of the box (via MCP), and your CI pipeline a doc freshness check that actually works.

Individual Developer — You're tired of spending the first hour on every task figuring out "how does this part of the system work?" beadloom ctx FEATURE-ID gives you the answer in seconds.

Key features

• Context Oracle — deterministic graph traversal, compact JSON bundle in <20ms
• Doc Sync Engine — tracks code↔doc relationships, detects stale documentation, integrates with git hooks
• Architecture as Code — define boundary rules in YAML, validate with beadloom lint, enforce in CI
• Full-text search — FTS5-powered search across nodes, docs, and code symbols
• Impact analysis — beadloom why shows what depends on a node and what breaks if it changes
• Code-first onboarding — bootstrap an architecture graph from code structure alone; no docs needed to start
• MCP server — 10 tools for AI agents, including write operations and search
• Interactive TUI — beadloom ui terminal dashboard for browsing the graph
• Local-first — single CLI + single SQLite file, no Docker, no cloud dependencies

How it works

Beadloom maintains an architecture graph defined in YAML files under .beadloom/_graph/. The graph consists of nodes (features, services, domains, entities, ADRs) connected by edges (part_of, uses, depends_on, etc.).

The indexing pipeline merges three sources into a single SQLite database:

1. Graph YAML — nodes and edges that describe the project architecture
2. Documentation — Markdown files linked to graph nodes, split into searchable chunks
3. Code — source files parsed with tree-sitter to extract symbols and # beadloom:feature=AUTH-001 annotations

When you request context for a node, the Context Oracle runs a breadth-first traversal, collects the relevant subgraph, documentation, and code symbols, and returns a compact bundle.

The Doc Sync Engine tracks which documentation files correspond to which code files. On every commit (via a git hook), it detects stale docs and either warns or blocks the commit.

Architecture as Code

Beadloom doesn't just describe architecture — it enforces it. Define boundary rules in YAML, validate with beadloom lint, and block violations in CI.

Rules (.beadloom/_graph/rules.yml) — real rules from this project:

rules:
  - name: domain-needs-parent
    description: "Every domain must be part_of the beadloom service"
    require:
      for: { kind: domain }
      has_edge_to: { ref_id: beadloom }
      edge_kind: part_of

  - name: feature-needs-domain
    description: "Every feature must be part_of a domain"
    require:
      for: { kind: feature }
      has_edge_to: { kind: domain }
      edge_kind: part_of

Validate:

beadloom lint                 # rich output in terminal
beadloom lint --strict        # exit 1 on violations (for CI)
beadloom lint --format json   # machine-readable output

Agent-aware constraints — when an agent calls get_context("why"), the response includes active rules for that node. Agents respect architectural boundaries by design, not by accident.

Supported languages for import analysis: Python, TypeScript/JavaScript, Go, Rust.

CLI commands

Command	Description
init --bootstrap	Scan code and generate an initial architecture graph
init --import DIR	Import and classify existing documentation
reindex	Rebuild the SQLite index from graph, docs, and code
ctx REF_ID	Get a context bundle (Markdown or --json)
graph [REF_ID]	Visualize the architecture graph (Mermaid or JSON)
search QUERY	Full-text search across nodes, docs, and code symbols
status	Project index statistics and documentation coverage
doctor	Validate the architecture graph
sync-check	Check doc↔code synchronization status
sync-update REF_ID	Review and update stale docs
lint	Validate code against architecture boundary rules
why REF_ID	Impact analysis — upstream deps and downstream dependents
diff	Show graph changes since a git ref
link REF_ID [URL]	Manage external tracker links on graph nodes
ui	Interactive terminal dashboard (requires beadloom[tui])
watch	Auto-reindex on file changes (requires beadloom[watch])
install-hooks	Install the beadloom pre-commit hook
setup-mcp	Configure MCP server for AI agents
mcp-serve	Run the MCP server (stdio transport)

MCP tools

Tool	Description
get_context	Context bundle for a ref_id (graph + docs + code symbols + constraints)
get_graph	Subgraph around a node (nodes and edges as JSON)
list_nodes	List graph nodes, optionally filtered by kind
sync_check	Check if documentation is up-to-date with code
get_status	Documentation coverage and index statistics
update_node	Update a node's summary or metadata in YAML and SQLite
mark_synced	Mark documentation as synchronized with code
search	Full-text search across nodes, docs, and code symbols

Configuration

All project data lives under .beadloom/ in your repository root:

• .beadloom/config.yml — scan paths, languages, sync engine settings
• .beadloom/_graph/*.yml — architecture graph definition (YAML, version-controlled)
• .beadloom/beadloom.db — SQLite index (auto-generated, add to .gitignore)

Link code to graph nodes with annotations:

# beadloom:feature=AUTH-001
# beadloom:service=user-service
def authenticate(user_id: str) -> bool:
    ...

Documentation structure

Beadloom uses a domain-first layout. Here is the actual structure from this project:

docs/
  architecture.md                                  # system design
  getting-started.md                               # quick start guide
  guides/
    ci-setup.md                                    # CI integration
  domains/
    context-oracle/
      README.md                                    # domain overview
      features/
        cache/SPEC.md                              # L1+L2 cache spec
        search/SPEC.md                             # FTS5 search spec
        why/SPEC.md                                # impact analysis spec
    graph/
      README.md
      features/
        graph-diff/SPEC.md
        rule-engine/SPEC.md
        import-resolver/SPEC.md
    doc-sync/
      README.md
    onboarding/
      README.md
    infrastructure/
      README.md
      features/
        doctor/SPEC.md
        reindex/SPEC.md
        watcher/SPEC.md
  services/
    cli.md                                         # 21 CLI commands
    mcp.md                                         # 10 MCP tools
    tui.md                                         # TUI dashboard

Each domain gets a README.md (overview, invariants, API). Each feature gets a SPEC.md (purpose, data structures, algorithm, constraints).

Context bundle example

beadloom ctx why --json returns a deterministic context bundle — graph, docs, and code symbols assembled via BFS in <20ms:

{
  "version": 2,
  "focus": {
    "ref_id": "why",
    "kind": "feature",
    "summary": "Impact analysis — upstream deps and downstream consumers via bidirectional BFS"
  },
  "graph": {
    "nodes": [
      { "ref_id": "why", "kind": "feature", "summary": "Impact analysis ..." },
      { "ref_id": "context-oracle", "kind": "domain", "summary": "BFS graph traversal, caching, search" },
      { "ref_id": "beadloom", "kind": "service", "summary": "CLI + MCP server" },
      { "ref_id": "search", "kind": "feature", "summary": "FTS5 full-text search" },
      { "ref_id": "cache", "kind": "feature", "summary": "ETag-based bundle cache" }
    ],
    "edges": [
      { "src": "why", "dst": "context-oracle", "kind": "part_of" },
      { "src": "context-oracle", "dst": "beadloom", "kind": "part_of" },
      { "src": "cli", "dst": "context-oracle", "kind": "uses" }
    ]
  },
  "text_chunks": ["... 10 doc chunks from SPEC.md files ..."],
  "code_symbols": ["... 146 symbols from traversed modules ..."],
  "sync_status": { "stale_docs": [], "last_reindex": "2026-02-13T..." }
}

BFS depth=2 from why traverses: why → context-oracle (parent domain) → sibling features (search, cache), services (cli, mcp-server), cross-domain deps (infrastructure, graph) — 10 nodes, 12 edges total.

Beads integration

A context loom for your beads.

Beadloom complements Beads by providing structured context to planner/coder/reviewer agents. Beads workers call get_context(feature_id) via MCP and receive a ready-made bundle instead of searching the codebase from scratch.

Beadloom works independently of Beads — the integration is optional.

Development

uv sync --dev              # install with dev dependencies
uv run pytest              # run tests
uv run ruff check src/     # lint
uv run ruff format src/    # format
uv run mypy                # type checking (strict mode)

Docs

Document	Description
architecture.md	System design and component overview
getting-started.md	Quick start guide
Domains
Context Oracle	BFS algorithm, context assembly, caching, search
Cache	L1 in-memory + L2 SQLite bundle cache
Search	FTS5 full-text search
Why	Impact analysis via bidirectional BFS
Graph	YAML graph format, diff, rule engine, linter
Graph Diff	Git ref comparison for graph changes
Rule Engine	Architecture-as-Code deny/require rules
Import Resolver	Multi-language import analysis
Doc Sync	Doc↔code synchronization engine
Onboarding	Project bootstrap and presets
Infrastructure	Database, health metrics, reindex
Doctor	Graph validation checks
Reindex	Full and incremental reindex pipeline
Watcher	Auto-reindex on file changes
Services
CLI Reference	All 21 CLI commands
MCP Server	All 10 MCP tools for AI agents
TUI Dashboard	Interactive terminal dashboard
Guides
CI Setup	GitHub Actions / GitLab CI integration

Known Issues

See UX Issues Log for the full list of known issues and limitations discovered during dogfooding.

Key open items:

• sync-check tracks file-level hash changes but does not detect semantic drift (code changed, doc content didn't) — [#15, #18]
• setup-rules auto-detection doesn't work for Windsurf/Cline (marker file = rules file) — [#17]
• AGENTS.md is not auto-generated during beadloom init --bootstrap — [#19]

License

MIT