🌐 SuperBrowser

An AI-native browser that searches across engines, understands what you're researching, and answers with context.

SuperBrowser pairs a multi-engine search aggregator with a context-aware AI that remembers what you've searched and read — per tab — to deliver smarter, grounded answers. It ships as both a web app and a cross-platform desktop app.

🚀 Quick Links


🌐 Live Web App	superbrowser-d6441.web.app
💾 Desktop App	Download `.exe` / `.dmg` / `.AppImage` from the live website
📦 Repository	github.com/PandyaJeet/SuperBrowser
🤝 Contributing	CONTRIBUTING.md · Code of Conduct

💡 Why SuperBrowser?

Traditional search hands you ten blue links and forgets everything the moment you click away. SuperBrowser does three things differently:

🔎 One query, many engines. It searches Google, Bing, and DuckDuckGo at once — with automatic scraper fallbacks if an API call fails — so you get broader, deduplicated results from a single box.
🧠 It remembers your research. Every query you run and every page you open is captured into a per-tab context. Open a new tab and you get a clean slate; stay in one and your trail compounds.
🤖 The AI uses that context. When you switch to AI mode and ask a follow-up, the assistant already knows what you've been looking at — so answers are grounded in your session, not generic.

The result is a research loop: Search → Context captured → Ask AI → Smarter answer.

✨ Features

🔍 SuperSEO — Multi-Engine Search

Aggregated results from Google, Bing, and DuckDuckGo behind one search box.
Resilient fallback: if SerpAPI returns nothing or errors, SuperBrowser transparently switches to direct web scrapers (BeautifulSoup) for the same engine.
Deduplication & ranking across sources, plus Google Shopping results for product queries.
Response caching with X-Cache: HIT/MISS headers to keep repeat searches fast.

🤖 SuperAI — Persona-Based, Context-Aware Chat

Five answer styles: default, chatgpt, gemini, perplexity, and claude, each driven by its own system prompt.
Smart live-data routing: a lightweight classifier decides whether your question needs fresh web data (prices, comparisons, news) or can be answered from the model's general knowledge — and only scrapes when it helps.
Grounded in your session: the assistant references your recent searches and visited pages for relevant, personalized answers.
Powered by Groq for low-latency inference across Llama 3.1/3.3, Mixtral, and Gemma models.

🗣️ Community Insights

Pulls real discussion from Stack Overflow, Reddit, Hacker News, and Dev.to.
AI-summarized into consensus, tips, debates, and warnings — so you skip the doom-scroll.

🧠 Per-Tab Context Engine

Automatically tracks your queries, results, and visited-page content (first ~5,000 chars).
Isolated per tab — each tab is its own research thread.
Visual context badge shows what's being tracked (🧠 Context: X searches, Y results).
One-click JSON export of an entire session for archival or sharing.

🖥️ Modern, Dual-Platform UI

Tab-based browsing with independent state per tab.
Dark / Light themes, persisted across sessions.
Smooth motion via Framer Motion, 3D accents via Three.js, and Markdown export of results.
Runs in the browser or as a native Electron desktop app (Windows / macOS / Linux).

⚙️ How It Works

   ┌──────────────┐   1. Search "react hooks"      ┌──────────────────────┐
   │   You type   │ ─────────────────────────────► │  Multi-engine search │
   │   a query    │                                │  (SerpAPI ↔ scrapers)│
   └──────────────┘ ◄───────────────────────────── └──────────────────────┘
          │              results returned + cached
          │
          ▼  2. Query + results auto-saved to this tab's context
   ┌──────────────────────────────────────────────────────────────┐
   │   🧠 Per-Tab Context:  queries · results · visited pages       │
   └──────────────────────────────────────────────────────────────┘
          │
          ▼  3. Switch to AI mode, pick a persona, ask a follow-up
   ┌──────────────┐    classify → (scrape if needed) → synthesize   ┌────────┐
   │   SuperAI    │ ◄───────────────────────────────────────────── │  Groq  │
   │  (context-   │                                                 │  LLMs  │
   │   aware)     │ ──► "Based on your searches about react hooks…" └────────┘
   └──────────────┘

🏗️ Architecture

SuperBrowser is a decoupled two-tier app: a React/Vite frontend talks to a FastAPI backend over REST. In desktop mode, Electron bundles and supervises the Python backend locally.

┌─────────────────────────────────────────────────────────────────────┐
│  FRONTEND — React 19 + Vite (web)  ·  Electron 39 (desktop)          │
│  ┌───────────┐  ┌────────────┐  ┌─────────────────────────────────┐ │
│  │  Tab Mgr  │  │ Search Bar │  │ useContextManager (per-tab hook)│ │
│  └───────────┘  └────────────┘  └─────────────────────────────────┘ │
└───────────────────────────────┬─────────────────────────────────────┘
                                │  REST  (http://localhost:8000/api/…)
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  BACKEND — FastAPI (Uvicorn, async)                                  │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│  │ /search/seo  │ │ /search/ai   │ │ /search/     │ │ /context/*  │ │
│  │              │ │ /contextual  │ │ community    │ │ (per tab)   │ │
│  └──────────────┘ └──────────────┘ └──────────────┘ └─────────────┘ │
│  query classifier · persona engine · summarizers · caching layer    │
└───────────────┬───────────────────────────────────┬─────────────────┘
                │                                     │
                ▼                                     ▼
        ┌───────────────┐                    ┌────────────────────┐
        │  SerpAPI      │  ── fallback ──►    │  Web Scrapers      │
        │  Groq LLM API │                     │  (BeautifulSoup)   │
        └───────────────┘                    └────────────────────┘

Note: Browsing context is scoped per session_id → tab_id, cached in memory, and persisted as JSON under CONTEXT_STORE_DIR. Context-chat messages use SQLite. Both locations can be redirected to durable storage.

🧰 Tech Stack

Layer	Technologies
Frontend	React 19, Vite, TailwindCSS, Framer Motion, Three.js / React Three Fiber, Recharts
Desktop	Electron 39, electron-builder (NSIS · DMG · AppImage)
Backend	Python 3.10+, FastAPI, Uvicorn, httpx, BeautifulSoup4, cachetools
AI & Search	Groq (Llama 3.1/3.3, Mixtral, Gemma), SerpAPI, custom scrapers
Hosting / CI	Firebase Hosting, GitHub Actions

🛠️ Getting Started

Prerequisites

Node.js 20.19+ or 22.12+ and npm
Python 3.10+ and pip
API keys for SerpAPI and Groq (see Configuration)

1. Clone the repo

git clone https://github.com/PandyaJeet/SuperBrowser.git
cd SuperBrowser

2. Start the backend

cd backend
pip install -r requirements.txt
cp .env.example .env

Now generate a session token — the backend will not serve any search or context route without one:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Put that value in backend/.env as SUPERBROWSER_SESSION_TOKEN, keep it handy for the frontend step, then start the server:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000, with interactive docs at http://localhost:8000/docs.

⚠️ If you skip the token, every /api/search/* and /api/context/* request returns HTTP 500 — "Server authentication not configured". The backend fails closed by design and prints a warning at startup telling you exactly this.

Port already in use? lsof -ti:8000 | xargs kill -9

3. Start the frontend

In a second terminal:

cd frontend
npm install
cp .env.example .env.local

Set VITE_SUPERBROWSER_SESSION_TOKEN in frontend/.env.local to the same token you put in backend/.env, then:

npm run dev -- --host 0.0.0.0

Open http://localhost:5173 in your browser. The frontend auto-detects its API base (local, Codespaces, or Electron), so no extra config is needed for local dev.

If the two tokens do not match, searches fail with a visible "Not authorised" banner. That is the expected signal — not a silent empty result list.

The desktop app needs neither variable: Electron generates its own token on first launch and injects it over IPC.

🔐 Configuration

Create a .env file inside the backend/ directory:

# Required — shared secret guarding /api/search/* and /api/context/*
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
SUPERBROWSER_SESSION_TOKEN=your_generated_token

# Required — powers SuperSEO search across Google, Bing & DuckDuckGo
SERPAPI_API_KEY=your_serpapi_key

# Required — powers all SuperAI responses & summaries
GROQ_API_KEY=your_groq_key

# Optional — CORS allow-list (comma-separated). Defaults to http://localhost:5173
ALLOWED_ORIGINS=http://localhost:5173

# Optional — where per-tab context JSON is persisted.
# Defaults to /tmp/superbrowser_contexts.
CONTEXT_STORE_DIR=/tmp/superbrowser_contexts

Variable	Required	Purpose	Get a key
`SUPERBROWSER_SESSION_TOKEN`	✅	Auth token for all search & context routes. Backend returns HTTP 500 on every gated route without it	generate locally (below)
`SERPAPI_API_KEY` (or `SERP_API_KEY`)	✅	Live search results for SuperSEO	serpapi.com
`GROQ_API_KEY`	✅	LLM inference for SuperAI & summaries	console.groq.com
`ALLOWED_ORIGINS`	⬜	CORS origins for the backend	—
`CONTEXT_STORE_DIR`	⬜	Directory for persisted per-tab context. Defaults to `/tmp/superbrowser_contexts`	—

Frontend environment

Create frontend/.env.local (template: frontend/.env.example):

Variable	Required	Purpose
`VITE_SUPERBROWSER_SESSION_TOKEN`	✅ (web build)	Must exactly match the backend's `SUPERBROWSER_SESSION_TOKEN`. Mismatched or missing ⇒ every search returns 401 and the UI shows a "Not authorised" banner
`VITE_API_BASE`	⬜	Override the auto-detected backend URL
`VITE_API_BASE_ELECTRON`	⬜	Override the backend URL in desktop mode

Generating the token — run once and use the same value on both sides:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Desktop app: neither token variable is needed. Electron generates its own token on first launch, stores it in settings.json, passes it to the backend it spawns, and attaches it over IPC — so it never reaches renderer JavaScript.

Live desktop search and AI still require provider credentials. In the desktop app, open Settings → Open provider key file, add SERPAPI_API_KEY and GROQ_API_KEY, save, and restart SuperBrowser. Electron creates this per-user provider-credentials.txt file in its user-data directory and passes it to the bundled backend through SUPERBROWSER_ENV_FILE; credentials are not embedded in the installer. Existing process environment variables take precedence.

Note: VITE_* values are bundled into the client build and are visible to anyone who loads the page. This token gates a self-hosted backend; it is not a per-user credential.

If any SerpAPI engine fails or returns nothing, SuperSEO automatically falls back to the matching web scraper — so search keeps working even without a perfect API response.

🖥️ Running the Desktop App

SuperBrowser can run as a native Electron app that spawns and supervises the Python backend for you.

cd frontend

# Dev: runs Vite + Electron together with hot reload
npm run dev:electron

# Build distributables
npm run dist:win     # Windows  → NSIS installer
npm run dist:mac     # macOS    → .dmg
npm run dist:linux   # Linux    → .AppImage

The distribution commands first build an isolated, pinned PyInstaller environment under backend/.pyi-build, produce a self-contained backend executable, and then bundle it with Electron. Python is required on the build machine but is not required on an end user's machine.

In desktop mode Electron selects an available loopback port, injects the endpoint through the preload bridge, stores app data under Electron's user-data directory, and terminates the backend process on application exit. A single-instance lock prevents duplicate primary instances.

📚 API Reference

All routes are served under http://localhost:8000. Full interactive docs (Swagger UI) live at /docs.

Search

Method	Endpoint	Description
`GET`	`/api/search/seo?q={query}`	Multi-engine search with scraper fallback.
`GET`	`/api/search/ai?q={query}&persona={p}&gl={region}`	AI answer (persona-styled, region-aware).
`POST`	`/api/search/ai/contextual`	AI answer using full browsing context (body below).
`GET`	`/api/search/community?q={query}`	Summarized insights from SO, Reddit, HN, Dev.to.

Example — contextual AI request

POST /api/search/ai/contextual
Content-Type: application/json

{
  "query": "How do I use these together?",
  "persona": "perplexity",
  "context": {
    "queries": ["react hooks", "useEffect"],
    "results": [ { "title": "...", "url": "...", "snippet": "..." } ],
    "visited_pages": [ { "url": "...", "content": "..." } ]
  }
}

persona is one of: default · chatgpt · gemini · perplexity · claude.

Context Management

Method	Endpoint	Description
`POST`	`/api/context/session/start`	Start a browsing session.
`POST`	`/api/context/add_query`	Add a query to a tab's context.
`POST`	`/api/context/add_results`	Add search results to a tab's context.
`POST`	`/api/context/add_visited_page`	Add visited-page content to context.
`GET`	`/api/context/get/{session_id}/{tab_id}`	Fetch a tab's context.
`GET`	`/api/context/export/{session_id}`	Export the full session context as JSON.
`POST`	`/api/context/chat`	Chat with the AI about your browsing context.
`DELETE`	`/api/context/clear/{session_id}/{tab_id}`	Clear one tab's context.

For deeper detail see CONTEXT_FEATURE.md and TESTING.md.

📂 Project Structure

SuperBrowser/
├── backend/                 # FastAPI app
│   ├── main.py              # App entry point & router mounting
│   ├── routers/             # seo · ai · community · context endpoints
│   ├── services/            # groq, super_ai, query_classifier, personas, summarizers
│   ├── scrapers/            # Google/Bing/DDG + SO/Reddit/HN/Dev.to scrapers
│   ├── utils/               # caching helpers
│   └── requirements.txt
├── frontend/                # React + Vite + Electron
│   ├── src/
│   │   ├── App.jsx          # App shell, tabs, search dispatch
│   │   ├── components/      # AiInput, CommunityResults, ProductCarousel, …
│   │   ├── config/apiBase.js# API base resolution (web/Codespaces/Electron)
│   │   └── useContextManager.js
│   └── electron/            # main.cjs, preload.cjs (desktop runtime)
├── systemprompt/            # Persona system prompts (perplexity, sonnet, …)
└── .github/workflows/       # CI: star-check, auto-label

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for setup, issue-claim, branch-naming, and PR conventions, and review our Code of Conduct.

For GSSoC contributions, comment your proposed approach on an issue and wait for assignment before coding.

⭐ Please star this repository before submitting a pull request. Starring is required for your PR to be merged. A star-check workflow reports whether the PR author has starred the repo, and maintainers will not merge unstarred contributions.

📄 License

Released under the MIT License.

👨‍💻 Authors

Profile	Name	GitHub
	Jeet Pandya	@PandyaJeet
	Prince Patel	@Princepatel-027

Contributors

Updates automatically as new contributors merge pull requests. Start contributing and see your profile here?

_{Built using React, FastAPI, and AI.}
⭐ If SuperBrowser helps you, give it a star!

Navigation Menu

Repository files navigation

🌐 SuperBrowser

An AI-native browser that searches across engines, understands what you're researching, and answers with context.

🚀 Quick Links

📋 Table of Contents

💡 Why SuperBrowser?

✨ Features

🔍 SuperSEO — Multi-Engine Search

🤖 SuperAI — Persona-Based, Context-Aware Chat

🗣️ Community Insights

🧠 Per-Tab Context Engine

🖥️ Modern, Dual-Platform UI

⚙️ How It Works

🏗️ Architecture

🧰 Tech Stack

🛠️ Getting Started

Prerequisites

1. Clone the repo

2. Start the backend

3. Start the frontend

🔐 Configuration

Frontend environment

🖥️ Running the Desktop App

📚 API Reference

Search

Context Management

📂 Project Structure

🤝 Contributing

📄 License

👨‍💻 Authors

Contributors

About

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
frontend		frontend
systemprompt		systemprompt
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTEXT_FEATURE.md		CONTEXT_FEATURE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
package-lock.json		package-lock.json

Latest commit

History

Folders and files

Repository files navigation

🌐 SuperBrowser

An AI-native browser that searches across engines, understands what you're researching, and answers with context.

🚀 Quick Links

📋 Table of Contents

💡 Why SuperBrowser?

✨ Features

🔍 SuperSEO — Multi-Engine Search

🤖 SuperAI — Persona-Based, Context-Aware Chat

🗣️ Community Insights

🧠 Per-Tab Context Engine

🖥️ Modern, Dual-Platform UI

⚙️ How It Works

🏗️ Architecture

🧰 Tech Stack

🛠️ Getting Started

Prerequisites

1. Clone the repo

2. Start the backend

3. Start the frontend

🔐 Configuration

Frontend environment

🖥️ Running the Desktop App

📚 API Reference

Search

Context Management

📂 Project Structure

🤝 Contributing

📄 License

👨‍💻 Authors

Contributors

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Used by

Contributors

Languages