Synapse – Browser‑LLM Bridge (API‑only)

---

📖 Table of Contents

• Overview
• Architecture Diagram
• Prerequisites
• Installation
• Running the Bridge
• Configuration (config.json)
• API Reference
  • Health & Usage
  • Ollama‑compatible Endpoints
  • OpenAI‑compatible Endpoints
  • Control Endpoints
• Usage Examples (cURL)
• Chrome Extension
• Security & Privacy
• FAQ
• Contributing
• License
• Contact & Support

---

🌟 Overview

Synapse is a head‑less bridge that enables any local application to interact with the browser‑based LLMs — ChatGPT, Claude, Gemini, and Arena — without requiring API keys or external billing. It provides:

• An Ollama‑compatible HTTP API (/api/*).
• An OpenAI‑compatible HTTP API (/v1/*).
• A WebSocket bridge (ws://localhost:8080) that talks to a Chrome extension which injects prompts and streams responses directly from the active web tab.

All traffic stays on the local machine; the bridge merely relays messages between your client and the already‑authenticated browser session.

---

📐 Architecture Diagram

┌─────────────────────┐   WebSocket   ┌─────────────────────────────────────┐   Chrome Scripting   ┌─────────────────────┐
│      Synapse API    │ ◀───────────── │      Synapse Bridge (Node.js)       │ ◀────────────────── │  Browser LLM Tab   │
│ (Ollama / OpenAI)   │ ──────────────► │  (ws://localhost:8080)             │ ───────────────────► │  (ChatGPT, Claude, │
│ http://localhost:8082│                └─────────────────────────────────────┘                     │  Gemini, Arena)   │
└─────────────────────┘                                                                              └─────────────────────┘

The bridge forwards JSON payloads from the HTTP API to the Chrome extension, which then interacts with the DOM of the target LLM provider.

---

📋 Prerequisites

• Node.js ≥ 16 (LTS recommended).
• Google Chrome (or any Chromium‑based browser) with the Synapse Chrome Extension installed.
• At least one tab open for the desired provider (e.g., https://chatgpt.com).

---

📦 Installation

# Clone the repository
git clone https://github.com/Parithosh-Varma/synapse-ai-bridge.git
cd synapse-ai-bridge

# Install runtime dependencies
npm install

The project purposefully keeps dependencies minimal—only ws for the WebSocket server and a few utilities for configuration handling.

---

🚀 Running the Bridge

# Start the head‑less bridge and HTTP API
npm start   # equivalent to `node server.js`

You should see output similar to:

[synapse] bridge listening on ws://localhost:8080 — waiting for Chrome extension...
[synapse] API ready — Ollama http://localhost:8082/api/tags · OpenAI http://localhost:8082/v1/models

• WebSocket bridge – ws://localhost:8080 (used internally by the extension).
• HTTP API – http://localhost:8082 (base URL for all endpoints).

The process stays alive until you terminate it (Ctrl‑C).

---

⚙️ Configuration (config.json)

A default config.json is created at the working directory on first run. Example:

{
  "port": 8080,
  "apiPort": 8082,
  "defaultAI": "chatgpt",
  "bell": true,
  "notify": true,
  "bg": "dark",
  "imageMode": "halfblock",
  "themeColor": "purple"
}

Key	Description
port	Port for the WebSocket bridge (default 8080).
apiPort	Port for the HTTP API (default 8082).
defaultAI	Fallback provider (chatgpt, claude, gemini, arena).
bell / notify	Audio / OS‑notification flags (kept for backward compatibility).
bg, imageMode, themeColor	UI‑related keys that are ignored in head‑less mode but retained for legacy configs.

Edit the file and restart the server to apply changes.

---

📡 API Reference

All endpoints accept and return JSON unless otherwise noted. The API mirrors both Ollama and OpenAI specifications, so existing client libraries work out‑of‑the‑box.

Health & Usage

Method	Path	Description
GET	/api/health	Returns { "online": true } when the bridge is connected to the Chrome extension.
GET	/api/usage	Aggregated usage statistics – request count, characters in/out, and estimated cost in USD.

Ollama‑compatible Endpoints

Method	Path	Request Body	Streaming?
GET	/api/tags	–	No
POST	/api/generate	{ model, prompt, stream?:false }	No (single response).
POST	/api/chat	{ model, messages, stream:true }	Yes – NDJSON (data: {...}\n\n).

OpenAI‑compatible Endpoints

Method	Path	Request Body	Streaming?
GET	/v1/models	–	No
POST	/v1/chat/completions	Same schema as OpenAI (model, messages, stream).	Yes – SSE (data: {...}\n\n).

Control Endpoints

Method	Path	Description
POST	/api/abort	Abort the currently running streaming request.
POST	/api/new	Instruct the extension to open a fresh tab for the current model.

---

💡 Usage Examples (cURL)

# List available models (Ollama style)
curl http://localhost:8082/api/tags

# Single completion (Ollama) – ChatGPT model
curl -X POST http://localhost:8082/api/generate \
     -H "Content-Type: application/json" \
     -d '{"model":"chatgpt","prompt":"Explain quantum entanglement in one sentence.","stream":false}'

# Chat with streaming (OpenAI style)
curl -N -X POST http://localhost:8082/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model":"claude","messages":[{"role":"user","content":"What is Rust?"}],"stream":true}'

# Abort a running request
curl -X POST http://localhost:8082/api/abort

Each request is relayed to the corresponding open browser tab, and the response is streamed back in real‑time.

---

🧩 Chrome Extension (unchanged)

The chrome-extension/ folder contains a Manifest V3 extension that:

1. Connects to the bridge (ws://localhost:8080).
2. Injects prompts into the active LLM tab and reads the DOM for streamed output.
3. Handles control messages (/switch, /new, /stop).

Installation steps

1. Open chrome://extensions/.
2. Enable Developer mode (top‑right toggle).
3. Click Load unpacked and select the chrome-extension/ directory.
4. Open at least one supported AI site (ChatGPT, Claude, Gemini, or Arena) and keep the tab open.

---

🔐 Security & Privacy

• Local‑only: All communication occurs on localhost; no external network traffic is involved.
• No API keys: The bridge never stores or transmits API credentials.
• Data residency: Prompt content and LLM responses remain within your browser session. The bridge only forwards raw strings.
• Extension permissions: The Chrome extension requests tabs, scripting, storage, and alarms—the minimal set required to interact with the page DOM.

---

❓ FAQ

Q: Do I need an OpenAI or Anthropic account?
A: No. Synapse works with the free tier of each provider as long as you are logged in via the browser.

Q: What happens if the extension disconnects?
A: The bridge logs a disconnection warning and retries automatically. Re‑load the extension if it stays disconnected.

Q: Can I use Synapse on a server without a GUI?
A: The bridge requires a headful Chrome instance to render the provider UI, so a machine with a graphical environment (or a virtual display such as Xvfb) is needed.

Q: How is usage cost calculated?
A: The API tracks characters in/out and applies a configurable per‑character estimate ($0.0015/1k for user input, $0.0020/1k for assistant output). This mirrors the original CLI cost meter.

---

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/…).
3. Ensure the server still starts (npm start).
4. Add tests if you introduce new endpoints.
5. Open a Pull Request with a concise description of the change.

All contributions are licensed under the same MIT terms.

---

📄 License

This project is released under the MIT License. See the LICENSE file for full terms.

---

📞 Contact & Support

• Author: Parithosh Varma – https://github.com/Parithosh-Varma
• Issues: Open a GitHub Issue for bugs, feature requests, or questions.
• Discord / Slack: Community discussions are welcome (link to community if existent).

---

Built with ❤️ by Parithosh Varma – https://github.com/Parithosh-Varma/synapse-ai-bridge