Skip to content

FAQ.md

Latest commit

 

History

History
197 lines (136 loc) · 6.29 KB

FAQ.md

File metadata and controls

197 lines (136 loc) · 6.29 KB
Raw

FAQ

Privacy & safety

Does any of my data leave my machine?

No. The Web UI binds to 127.0.0.1 and there are zero outbound network calls in the codebase. Nothing is sent to any cloud service.

You can verify with:

.venv/bin/python -m context_bridge.cli ui --host 127.0.0.1

127.0.0.1 is unreachable from any other machine on the network. If you want to access the UI from another device on your LAN, use --host 0.0.0.0 (and be aware that anyone on your network can then read your prompts).

Does ContextBridgeAI change anything about my IDEs?

No. We open IDE storage files read-only (with SQLite's mode=ro&immutable=1 URI for .vscdb files). We do not modify configuration, settings, MCP setup, extensions, or chat history of any IDE.

What's stored in data/?

File Contents
data/index.db SQLite with one row per session (the full normalized JSON), plus FTS5 indexes
data/semantic_index.pkl Cached embedding vectors (built when you click Re-index)
data/icons/* Extracted app icons / bundled SVG fallbacks

Delete the data/ folder to wipe everything ContextBridgeAI knows about.

Performance

First-run is slow — what's it doing?

The initial scrape walks every adapter and serializes every transcript into SQLite. On a Mac with ~2 700 sessions across 13 adapters, this takes ~10-30 seconds end-to-end. The biggest contributors:

  • Cursor: ~100 k bubbles to join
  • Codex CLI: ~200 rollouts with up to 500 turns each
  • Kiro: ~25 conv directories × multiple execution JSONs

All subsequent loads use the cached data/index.db and start instantly.

Why is the watcher polling instead of using inotify/FSEvents?

We tried it. Two problems:

  1. SQLite databases mutate via *-wal files (Write-Ahead Logging); the OS-level file-change events fire unpredictably.
  2. watchdog adds a heavy dependency that doesn't reliably catch the exact "session was updated" moment anyway.

The 3-second poll costs ~5 ms of CPU per cycle (sum of os.stat calls across all watched files). For the latency UX we want, that's an obvious trade.

Can I make the watcher faster?

Yes:

CONTEXT_BRIDGE_WATCH_INTERVAL=1 make ui   # 1-second poll

Or disable it entirely if you don't need live updates:

CONTEXT_BRIDGE_NO_WATCH=1 make ui

Search is slow on first use after restart

The semantic-vector matrix has to be loaded into memory on the first search after a fresh start (a few hundred MB for ~3 000 sessions with sentence-transformers, much smaller for the hashed-TF-IDF fallback). Subsequent searches reuse the in-memory matrix and are instant.

Adapter limitations

Why does Continue show 0 sessions?

Because you haven't generated any Continue.dev sessions on this Mac. The adapter is fully working — it just has nothing to read. Open a Continue chat in VS Code and within 3 seconds the watcher will pick it up.

Why are Gemini sessions shown as placeholders?

Google encrypts Gemini conversation files (*.pb) on disk. The plaintext is not recoverable without Google's private key. To still give you a useful timeline, we emit a placeholder transcript per file showing the file name, size, timestamps, and a note explaining the encryption. Open the Antigravity app itself to view the actual chat.

Why is Cursor's count lower than I'd expect?

Cursor stores its data in a 2 GB SQLite file (globalStorage/state.vscdb). We extract every composerData:* chat and join it with all bubbleId:*:* rows. If you see a low count, it's likely because you recently logged into a new account or wiped Cursor's storage. Run cli test-extract to see what's actually on disk.

Windsurf sessions are just gibberish — why?

Windsurf's chat_state/*.pb files are protobuf without a published schema. We use the salvage pattern (extract long printable byte runs) which produces a searchable text dump but loses turn boundaries. If Codeium ever publishes the schema, we can do better — PRs welcome.

Troubleshooting

"No sessions found" after install

  1. Make sure you ran make install and the venv exists (ls .venv).
  2. Run the diagnostic: 
    .venv/bin/python -m context_bridge.cli test-extract
    Every adapter should report whether it's available=True/False and how many sessions it found.
  3. If an adapter says available=True but extracted: 0, the source directory exists but has no parseable content. Check the path listed in ADAPTERS.md.

"Search index 12h old" but I want fresh results

Click the yellow Re-index button in the UI header. Or from the CLI:

.venv/bin/python -m context_bridge.cli index

Port 8765 is already in use

.venv/bin/python -m context_bridge.cli ui --port 8770   # any free port

The UI shows an old session at the top — newer ones missing

The watcher detects file changes by (size, mtime). If your filesystem isn't updating mtimes (rare, but happens on some networked drives), force a re-scrape:

.venv/bin/python -m context_bridge.cli index

How do I uninstall completely?

make clean      # removes .venv/ and data/
rm -rf .       # delete the project folder

No global state is left behind — ContextBridgeAI doesn't install any system-wide files, daemons, or configurations.

Roadmap-y questions

Will this support Linux / Windows?

The architecture is OS-agnostic, but most current adapters use ~/Library/Application Support/... paths that are macOS-specific. For each adapter we'd need to add the equivalent Linux (~/.config/..., ~/.local/share/...) and Windows (%APPDATA%\...) paths. PRs welcome.

Will there be a cloud/multi-user version?

That requires fundamentally different architecture (auth, multi-tenant storage, remote sync agent). Out of scope for the local tool, but the groundwork is here if someone wants to fork it.

Why not just write an MCP server?

An earlier prototype did. The problem: MCP today has no way for a server to observe what an agent is doing turn-by-turn — only respond when called. So an MCP-only ContextBridge would need every agent to voluntarily call our tool every turn. The file-scraping approach gives us 100 % coverage without that cooperation. (We'd happily revisit MCP if/when the spec adds a turn-subscription primitive.)