Contributing to SurfSense

March 25, 2026 · View on GitHub

Hey! 👋 Thanks for checking out SurfSense. We're stoked that you're interested in helping improve the project. Whether it's fixing bugs, suggesting features, improving docs, or just joining the conversation — every bit helps.

🧠 Before You Start

Join Our Discord
Want to stay in the loop, ask questions, or get feedback before starting something?
Hop into the official SurfSense community:
👉 https://discord.gg/ejRNvftDp9

That's where the latest updates, internal discussions, and collaborations happen.

📌 What Can You Work On?

There are 3 main ways to contribute:

✅ 1. Pick From the Roadmap

We maintain a public roadmap with well-scoped issues and features you can work on:
🔗 SurfSense GitHub Project Roadmap

💡 Tip: Look for tasks in Backlog or Ready status.

💡 2. Propose Something New

Have an idea that's not on the roadmap?

First, check for an existing issue
If it doesn't exist, create a new issue explaining your feature or enhancement
Wait for feedback from maintainers
Once approved, you're welcome to start working on a PR!

🐞 3. Report Bugs or Fix Them

Found a bug? Create an issue with:

Steps to reproduce the issue
Expected vs actual behavior
Environment details (OS, browser, version)
Any relevant logs or screenshots

Want to fix it? Go for it! Just link the issue in your PR.

🌿 Branching Workflow

We follow a branch protection model to keep main stable:

Branch	Purpose	Who can merge
`main`	Stable/release branch	Maintainers only (from `dev`)
`dev`	Active development & integration	Via approved PRs from contributors
`feature/`, `fix/`, etc.	Individual work branches	Contributors create PRs to `dev`

Important Rules

All contributor PRs must target the dev branch. PRs targeting main will not be accepted.
main is updated exclusively by maintainers merging from dev when a release is ready.
Always create your feature/fix branches from the latest dev.

🛠️ Development Setup

Prerequisites

Docker & Docker Compose (recommended) OR manual setup
Node.js (v18+ for web frontend)
Python (v3.11+ for backend)
PostgreSQL with PGVector extension
API Keys for external services you're testing

Quick Start

Fork and clone the repository

git clone https://github.com/<your-username>/SurfSense.git
cd SurfSense

Create your branch from dev

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

Choose your setup method:
- Docker Setup: Follow the Docker Setup Guide
- Manual Setup: Follow the Installation Guide
Configure services:
- Set up PGVector & PostgreSQL
- Configure a file ETL service: Unstructured.io or LlamaIndex
- Add API keys for external services

For detailed setup instructions, refer to our Installation Guide.

🏗️ Project Structure

SurfSense consists of three main components:

surfsense_backend/ - Python/FastAPI backend service
surfsense_web/ - Next.js web application
surfsense_browser_extension/ - Browser extension for data collection

🧪 Development Guidelines

Code Quality & Pre-commit Hooks

We use pre-commit hooks to maintain code quality, security, and consistency across the codebase. Before you start developing:

Install and set up pre-commit hooks - See our detailed Pre-commit Guide
Understand the automated checks that will run on your code
Learn about bypassing hooks when necessary (use sparingly!)

Code Style

Backend: Follow Python PEP 8 style guidelines
Frontend: Use TypeScript and follow the existing code patterns
Formatting: Use the project's configured formatters (Black for Python, Prettier for TypeScript)

Commit Messages

Use clear, descriptive commit messages:

feat: add document search functionality
fix: resolve pagination issue in chat history
docs: update installation guide
refactor: improve error handling in connectors