Skip to content

USER_GUIDE.md

Latest commit

 

History

History
243 lines (172 loc) · 7.61 KB

USER_GUIDE.md

File metadata and controls

243 lines (172 loc) · 7.61 KB
Raw

User Guide

ContextBridgeAI gives you one place to browse, search, and export every prompt you've ever sent to an agentic IDE or AI CLI on your Mac. This guide walks through everything the UI and CLI can do.

1. Installation

git clone <repo>
cd ContextBridgeAi
make install

Optional but recommended for better fuzzy search:

make install-full   # adds sentence-transformers (~250 MB)

Optional — extract the real macOS app icons (one-off; auto-uses bundled SVG fallbacks if you skip it):

.venv/bin/python scripts/extract_app_icons.py

2. Running the Web UI

make ui                   # http://127.0.0.1:8765
# or
.venv/bin/python -m context_bridge.cli ui --port 8770

On first launch the watcher does a full scrape of all 13 adapters. After that it polls every 3 seconds and auto-picks-up new sessions.

Stop with Ctrl+C in the terminal.

Environment variables

Variable Default Effect
CONTEXT_BRIDGE_WATCH_INTERVAL 3 Seconds between watcher polls
CONTEXT_BRIDGE_NO_WATCH unset If set, disables the watcher entirely

3. The 3-pane layout

┌────────────────────────────────────────────────────────────────────────┐
│ HEADER:  search box  ·  [ Search ]  ·  [ Re-index · search 5m old ]    │
├────────────┬───────────────────────┬───────────────────────────────────┤
│  APPS      │  SESSIONS             │  VIEWER                           │
│  (left)    │  (middle)             │  (right)                          │
└────────────┴───────────────────────┴───────────────────────────────────┘

Apps pane (left)

  • ✦ All apps — pick this to browse every session from every IDE
  • Apps split into Recently Active (≤ 14 days) and Earlier
  • Each card shows:
    • Real app icon (extracted from /Applications/<X>.app) or an SVG fallback for CLI tools
    • App name (capitalized, prettified)
    • Compact stats: Ns · Nm · relative-date
    • Recency dot on the icon: 🟢 today/yesterday · 🔵 this week · ⚪ this month
    • Count pill on the right
  • Tooltip on hover shows full exact timestamps and counts

Sessions pane (middle)

Sessions are always sorted most-recent first and grouped by date with a count badge per date group:

─── TODAY ───────────────────────────── [ 2 ]   (green when applicable)
   ┃ Session card (color-coded by app)
─── YESTERDAY ──────────────────────── [ 1 ]
   ┃ Session card
─── SUNDAY ─────────────────────────── [ 2 ]
─── MON, MAY 18 ────────────────────── [ 1 ]

Each session card shows:

  • Title (2-line clamp; falls back to the first user message)
  • A colored left rail matching the app
  • App name · model · relative date
  • Message count pill
  • 📁 short workspace path (full path on hover)

Click a card to open it in the viewer.

Viewer pane (right)

Tabbed viewer with three modes:

Tab What you get
Rendered Role-colored message bubbles. System / user / assistant / tool / tool_call each get a distinct left-border color.
Plain text The entire conversation as a single <SYSTEM>…</SYSTEM>\n<USER>…</USER>\n… blob — perfect for copy/paste into a docs/blog post
JSON The raw PromptTranscript schema

Two download links in the tab strip — .txt and .md — open the exported transcript in a new tab.

The header shows the model, provider, workspace path, raw source file location, and total message count.

4. Hybrid search

Type into the box and hit Search (or press Enter).

ContextBridgeAI runs two retrievals in parallel and fuses them with Reciprocal Rank Fusion (k=60):

  • BM25 via SQLite FTS5 (exact keyword and rare-term recall)
  • Semantic via all-MiniLM-L6-v2 if installed, else hashed-TF-IDF cosine (paraphrase / conceptual recall)

Each search result is rendered as a session card with an extra snippet block:

🟣 Rovo Dev · MCP Context & Prompt Manager       [ 800 ]
…context-bridge: search my past prompts about MCP…
🎯 score 0.0269 · bm25 #19 · semantic #3
  • 🎯 score = fused RRF score (higher = better)
  • bm25 #N = rank in the BM25 result list (or —)
  • semantic #N = rank in the semantic result list (or —)

Highlighted terms appear in <mark> yellow.

Clear the search box and press Enter to go back to plain browse mode.

5. Re-index button (top-right)

The button has three possible states:

State Label When
Fresh Re-index · search 49s old (gray) Index is up-to-date
Stale Re-index · search 5m old (🟡 yellow background) Data has changed since last index
Never built Build index · never built (🟡 yellow) Fresh install

Click it to rebuild the semantic search vectors (BM25 stays fresh automatically via SQLite triggers — you only need this for the semantic side).

Why isn't it automatic? Encoding 2 700+ transcripts takes a few seconds and we don't want it churning while you type.

6. Live updates

The watcher (3 s poll) keeps data/index.db fresh. When new sessions appear, the UI banner briefly shows:

🟢 live · rovodev+2

…and the apps pane reorders so the freshly-active app moves to the top of Recently Active.

7. The CLI

Every UI feature has a CLI equivalent:

Command Purpose
cli index Full scrape + rebuild semantic index
cli list-apps Table of all apps + counts + availability
cli list-sessions [--app X] [--limit N] Recent sessions
cli search "query" [--limit N] Hybrid search
cli export <session_id> [-f text|markdown|json] [-o file] Export
cli verify-current Find current workspace's most-recent Rovo Dev session and print summary
cli test-extract Run every adapter; print session counts (diagnostic)
cli ui [--host H] [--port P] Launch Web UI

Examples:

# Save your *current* Rovo Dev session as plain text
.venv/bin/python -m context_bridge.cli verify-current

# Find all your past chats about MCP
.venv/bin/python -m context_bridge.cli search "MCP context manager"

# Export a Codex session to markdown
.venv/bin/python -m context_bridge.cli export codex:019b3c46-… -f markdown

8. Where everything is stored

Path What
data/index.db SQLite (all transcripts + FTS5)
data/semantic_index.pkl Cached semantic vectors
data/icons/*.png *.svg Extracted/bundled app icons
.venv/ Local virtualenv

Delete the data/ directory to wipe the entire index. Nothing else on your machine is touched by ContextBridgeAI.

9. Stop, uninstall

# Stop the UI: Ctrl+C in its terminal
# Wipe the index:
make clean       # removes .venv and data/ artifacts

No IDE configuration is modified by ContextBridgeAI, so uninstalling is just deleting the project folder.

10. Troubleshooting

See FAQ.md — covers slow first-run, missing sessions, why Gemini chats are placeholders, etc.