ContextBridge

Why ContextBridge?

Without CB, an AI coding agent either guesses which files are relevant, or you paste entire source files into the chat — burning thousands of input tokens on code that isn't needed.

With CB, the AI calls a single MCP tool and gets back a compact, ranked result: the owner file, related files, key symbols, and a dependency summary — typically a few hundred tokens instead of tens of thousands of lines of raw source.

This isn't limited to bug investigations — the same tool answers general questions about how an existing feature or workflow is implemented.

| Without CB | With CB | |---|---| | Paste 10–50 raw files into context | CB returns the 3–5 files that actually matter | | AI guesses which code is relevant | Result is grounded in your real codebase structure | | High token cost, noisy context | Low token cost, focused context | | Hallucinated file paths and method names | Exact file paths, symbols, and line hints |

The optional local AI analysis stage further compresses the result before it reaches your cloud AI — so you pay even less.

Scope note: ContextBridge is a codebase routing and retrieval tool, not a reasoning engine — it finds the right files, symbols, and connections, but does not prove causality or choose the fix for you. See Intended Scope for the full boundary.

---

💡 New here? Don't want to read everything? Ask your AI assistant (Claude, ChatGPT, Gemini, etc.) to read the docs/ folder and guide you through setup for your OS and project.

A local-first code retrieval layer for AI coding agents. ContextBridge indexes your codebase (via Graphify output), then exposes MCP tools that any AI client (Claude Code, Codex, Cursor, Antigravity, …) can call to get ranked files, symbols, and dependency chains — optionally validated and re-ranked by a local LLM before the answer reaches your cloud AI.

Your prompt ─► ContextBridge (keyword + vector retrieval)
            ─► Local AI (optional: validates, re-ranks, fills gaps)
            ─► Your AI agent (implements, grounded in real files)

The engine is generic. All project-specific ranking lives in a swappable profile plugin, so the same tool works for any codebase.

---

Architecture

How your code flows through ContextBridge to your AI agent:

<p align="center"> <img src="docs/assets/architecture.png" alt="ContextBridge architecture and data flow" width="720"> </p>

---

Dashboard

ContextBridge ships with a local dashboard for monitoring retrieval quality, index health, and config — no cloud dependency.

<p align="center"> <img src="docs/assets/screenshots/overview.png" alt="ContextBridge dashboard overview" width="800"><br> <em>Overview — retrieval quality, token savings, and search-mode breakdown</em> </p> <p align="center"> <img src="docs/assets/screenshots/settings.png" alt="ContextBridge dashboard settings" width="800"><br> <em>Settings — tune pipeline mode, RAG weights, and model config live</em> </p> <p align="center"> <img src="docs/assets/screenshots/token-savings.png" alt="Token savings breakdown modal" width="800"><br> <em>Token savings — per-query breakdown of what CB delivered vs. full-file cost</em> </p>

---

📖 Before you start — read the docs. The docs/ folder contains everything you need for full setup, configuration, pipeline, and profile creation. Start with docs/0. README.md for a guided index of all documentation.

---

Quick start

:: 1. Install deps + build the index + scaffold config files
context_bridge\setup\windows\setup_context_bridge.bat

:: 2. Point the config at YOUR source folders
::    edit config.hybrid.json  ->  settings.discovery.*  (replace your_backend / your_frontend)

:: 3. Re-run setup to index your code
context_bridge\setup\windows\setup_context_bridge.bat

:: 4. Start the server + dashboard (pick Hybrid / Semantic / Keyword)
context_bridge\setup\windows\1.  start_Context_Bridge.bat

Mac/Linux: use context_bridge/setup/mac/ or context_bridge/setup/linux/ equivalents.

Setup is rerunnable and safe: it creates config/start files from the *.example templates only if missing (never overwrites your edits), and rebuilds the index each run. Run setup_context_bridge.bat --force to reset configs back to the templates.

The MCP server runs SSE by default at http://127.0.0.1:8755/sse — point your AI client there. Stdio transport is also supported (set CONTEXT_BRIDGE_TRANSPORT=stdio before starting) for clients that don't support SSE; SSE is recommended since it lets multiple AI clients share one running server instead of each spawning its own process. Dashboard: http://127.0.0.1:8795. Live stats can lag up to ~15 seconds behind the latest activity, and history lists (recent events, missed files, failed queries) show the most recent 1000 entries rather than the full lifetime log — both are intentional performance tradeoffs, not data loss.

---

Retrieval modes

Chosen at startup (the start script picks the matching config file):

| Mode | Config | What it does | |---|---|---| | Hybrid | config.hybrid.json | Keyword-first + guarded vector assist (recommended) | | Semantic | config.semantic.json | Vector-only (needs sentence-transformers) | | Keyword | config.json | Pure keyword, no vectors |

---

MCP tools

| Tool | Use | |---|---| | search_context_hybrid() | Primary — broad file + context discovery (runs analysis automatically) | | find_code_locations() | Exact owner file / symbol / line for a method or class | | get_module_summary() | Overview of a module/service | | get_graphify_pack() | All files in a feature pack | | record_outcome() | Log whether a result helped | | health_check(), get_usage_summary(), search_context(), find_related_files() | Utility |

Which tools appear is controlled by config — if a tool is registered, it is safe to call.

---

Writing your own profile

The generic engine asks a profile for project-specific ranking at every step. With no profile (project_profile: "default") you get pure generic scoring.

1. Copy rules/projects/example_profile.py → rules/projects/<yourapp>_profile.py
2. Implement the hooks you need (every hook is optional — skipped hooks fall back to no-op)
3. Activate it: set CONTEXT_BRIDGE_PROFILE=<yourapp> in your start script, or project_profile: "<yourapp>" in your config

Profile hooks (all optional)

| Hook | Purpose | |---|---| | expand_query_tokens(query, tokens) | Add extra search tokens | | module_intent_tokens() | Map module name → vocabulary | | pinned_owner_files(query_tokens) | Force specific files to the top | | adjust_document_score(...) | Boost/penalize a candidate document | | adjust_owner_score(...) | Boost/penalize an owner file by name | | adjust_primary_owner_score(...) | Nudge the single primary owner | | adjust_scoped_score(...) | Prefer files under the dominant module/pack | | extra_owner_file_patterns() | Extra high-priority filename patterns | | infer_module_from_path(path) | Path → module name (fusion scoping) | | low_signal_terms() | Module/domain words to treat as low-signal | | noise_files() | Filenames to de-prioritize (ui/support/root) | | gap_queries() | Trigger words → clean re-search query | | analysis_prompt_override() | Full system prompt for the local AI | | pack_files_for_intents(...) | Map intents → Graphify pack files (advanced) |

See docs/ for extended guides on setup, pipeline, profile creation, and debug commands.

---

Indexing

ContextBridge indexes Graphify output (graph.json, GRAPH_REPORT.md, source-files.txt, scope-summary.md, manifest.json) plus /behavior/ docs — not raw source. Generate Graphify for your project, point settings.discovery.* at those folders, and run setup. Re-run setup after each Graphify update to refresh the index.

---

Local AI (optional)

Configure a local model under pipeline.analysis_stage (provider ollama by default, or anthropic/openai/openrouter). When enabled, it validates and re-ranks CB results, decomposes multi-topic prompts, and triggers gap re-searches — then passes a compact, grounded result to your cloud AI. Swap models by changing model only; the prompts are model-agnostic.

---

License

Copyright 2026 Tiju Thomas

Licensed under the Apache License, Version 2.0.