Context Bridge

Context Bridge is a local-first pipeline between a repository and external LLMs or MCP clients. It is intentionally narrow: it packs bounded repository context, ranks files and symbols with a tree-sitter/PageRank graph, applies structured SemPatch YAML through AST matching, and writes changes through a transaction layer with verification hooks.

It is not a full coding agent. It does not plan large refactors end to end. It focuses on the I/O boundary: what leaves the repo, and what comes back in.

What It Does

• pack repository context with manifests, byte limits, secret scanning, and optional visual snapshots,
• build repository maps from tree-sitter tags and reference scores,
• select task-relevant files within a token budget,
• apply SemPatch YAML with transactional prepare/commit semantics,
• expose the same primitives through CLI, MCP, and an agent skill,
• pair with a browser companion so web LLMs can operate on local code without copy/paste loops.

Install

python -m pip install -e .
python -m pip install -e ".[mcp,visual]"

Quick Start

Generate a repository map:

context-bridge map . --query "fix login token refresh" -o repo-map.md

Select a bounded bundle:

context-bridge select . --task "fix login token refresh" -o selected-context.md

Create a staged plan:

context-bridge playbook . --task "fix login token refresh" -o playbook.md

Apply a SemPatch response:

context-bridge apply answer.md --root .
context-bridge apply answer.md --root . --write

Migrate a legacy patch file once:

context-bridge migrate-old-patches legacy-answer.md -o answer.sempatch.md

SemPatch

SemPatch is the required patch format. Each block is explicit YAML:

--- sempatch ---
file: src/example.py
language: python
op: replace
selector:
  rule:
    pattern: |
      def hello():
        $$$BODY
replacement: |
  def hello():
      return "updated"
--- end sempatch ---

Use op: create_file with content: for new files. The tool validates the structure, matches exactly one AST node, and runs inside a transaction when writing.

MCP

context-bridge mcp

The MCP server exposes pack_context, repo_map, context_playbook, select_context_for_task, scan_text_for_secrets, inspect_sempatches, apply_patches, and sempatch_schema.

Browser Companion

The browser companion follows the same shape as existing Chrome/MCP bridge projects: prefer Chrome Native Messaging for the local host boundary, then fall back to the loopback HTTP bridge when native host registration is not available.

context-bridge ext native-manifest --extension-id <installed-extension-id> --output native-host.json
context-bridge ext serve

The extension/ directory is a Chrome MV3 companion. It calls the native host com.context_bridge.native_host first and uses context-bridge ext serve only as a fallback.

Verification

Configure verify hooks in .context-bridge.toml:

[verify]
typescript = ["pnpm", "exec", "tsc", "--noEmit"]
python = ["python", "-m", "ruff", "check", "--quiet"]
rust = ["cargo", "check", "--quiet"]

apply --write runs verification by default. Use --no-verify only when you knowingly want to skip the hooks.

Visual Snapshots

bundle --visual does not ship a custom component renderer. It reuses an existing Storybook, Ladle, or Histoire setup in the target project and captures it with Playwright:

[visual]
explorer = "storybook"
command = ["npm", "run", "storybook", "--", "--ci", "--port", "6006"]
url = "http://127.0.0.1:6006"
timeout_seconds = 45

If no story exists for a component, Context Bridge reports that clearly instead of emitting a fake snapshot.

Development

python -m unittest discover -s tests -v
python -m compileall -q src tests