gitwtfhub

wtf is surfsense?

modsetter/surfsense — explained in plain English

Analysis updated 2026-06-24

14,210PythonAudience · generalComplexity · 3/5Setup · moderate

TL;DR

SurfSense is a self-hostable AI knowledge base where you connect documents, cloud drives, and local folders, then ask questions and get cited answers, written reports, and audio summaries.

Mindmap

mindmap
  root((surfsense))
    What it does
      AI question-answering
      Cited answers
      Report generation
    Data sources
      Google Drive
      Notion and Dropbox
      Local folders
    Output types
      Text answers
      PDF and Word reports
      Audio summaries
    Deployment
      Self-hosted Docker
      Cloud at surfsense.com
    Audience
      Researchers
      Teams
      Knowledge workers

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Connect Google Drive or Notion and ask an AI questions about your documents with source citations

REASON 2

Point a folder-watch at your Obsidian vault to auto-sync notes and chat with them via AI

REASON 3

Generate a podcast-style audio summary or a PDF report from a collection of documents

REASON 4

Share a notebook with teammates to collaboratively question a shared knowledge base in real time

What's in the stack?

PythonDocker

How it stacks up

modsetter/surfsensesfttech/openagepaddlepaddle/paddledetection
Stars14,21014,20814,205
LanguagePythonPythonPython
Setup difficultymoderatehardhard
Complexity3/55/54/5
Audiencegeneraldeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Self-hosting uses a single Docker install command, but you need to configure credentials for your chosen AI provider.

Wtf does this do

SurfSense is an open source tool for building a personal or team knowledge base that you can then question with an AI. The README positions it as an alternative to Google NotebookLM, a tool that lets you add documents and ask questions about them. The main differences the project claims are: no limits on how many documents or notebooks you can have, no lock-in to one AI provider, and the option to run the whole thing on your own server so your data never leaves your control. You add sources by connecting cloud storage services like Google Drive, OneDrive, Dropbox, or Notion, or by uploading files directly. The system indexes everything and lets you ask questions that come back with citations pointing to the original source material. Beyond question-and-answer, it can generate written reports in formats like PDF or Word, produce podcast-style audio summaries, and create images. A real-time collaboration feature lets multiple team members share a notebook and chat together. A desktop app is available alongside the web interface. It adds a global keyboard shortcut to bring up an AI assistant from any application, a mode where you select text on screen and ask the AI to explain or rewrite it, a screenshot mode where you can capture part of your screen and ask questions about it, and a folder-watching feature that automatically syncs a local folder to your knowledge base as files change. The README suggests pointing the folder watch at an Obsidian notes vault as one use case. Self-hosting uses Docker and takes a single install command on Linux, macOS, or Windows. The cloud version is available at surfsense.com. The app supports multiple languages including English, Spanish, Portuguese, Hindi, and Chinese. You can configure which AI models handle text, images, speech-to-text, and text-to-speech, including models you run locally.

Yoink these prompts

Prompt 1
I've self-hosted SurfSense with Docker. How do I connect my Google Drive as a source and start asking questions about my files?
Prompt 2
Set up SurfSense's folder-watch feature to automatically sync my Obsidian vault at ~/Documents/notes into a SurfSense notebook.
Prompt 3
Using SurfSense, generate a written PDF report summarizing all documents I've added on the topic of machine learning trends.
Prompt 4
I want to run SurfSense with a local AI model instead of a cloud provider. Which configuration settings do I change?
Prompt 5
How do I invite a teammate to a SurfSense notebook so we can both query the same knowledge base?

Frequently asked questions

wtf is surfsense?

SurfSense is a self-hostable AI knowledge base where you connect documents, cloud drives, and local folders, then ask questions and get cited answers, written reports, and audio summaries.

What language is surfsense written in?

Mainly Python. The stack also includes Python, Docker.

How hard is surfsense to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is surfsense for?

Mainly general.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.