The first fully open-source Developer Experience suite for GitHub-native teams

Changelog · Contributing · Security

_{Dashboard: team pulse, blockers, and activity at a glance}

What is sparQ

sparQ is the first fully open-source Developer Experience suite for GitHub-native teams. It's a set of focused products that share one self-hosted home. Start with Pulse today, with Metrics and Knowledge on the way.

Pulse

GitHub-native project management, async standups, team presence, and delivery visibility for teams living in GitHub. Self-hosting is always free. Forever.

Runs on SQLite out of the box. Zero external dependencies.

Features

• GitHub Sync — Projects, tasks, and status derived from PRs, issues, and commits
• Async Standups — Template-driven daily check-ins with audio recording and transcription
• Blockers Board — Track blockers with owners, urgency tiers, and automatic nudges
• Presence — See who's available, focused, blocked, or out across the team
• Action Items — Three-tier urgency system (Now / Later / Whenever), weekly plans
• Chat & DMs — Real-time messaging with channels, direct messages, and reactions
• Documents — Notes, e-signatures with audit trail, knowledge base
• People — Directory, onboarding, 1-on-1s, hiring pipeline
• Time & Attendance — Clock in/out, PTO requests, schedules, punch corrections
• AI Assistant — Optional LLM-powered features (OpenAI or Anthropic)
• Mobile API — Full REST API with JWT auth
• Multi-language — Built-in i18n with installable language packs

Quick Start

Option 1: Docker (recommended)

git clone https://github.com/sparqsoft/sparq.git
cd sparq
docker compose up

Open http://localhost:8000 to get started.

Option 2: Local development

Requires Python 3.13+ and uv.

git clone https://github.com/sparqsoft/sparq.git
cd sparq/pulse
make venv
source venv/bin/activate
make run

Open http://localhost:8000.

Option 3: PostgreSQL

By default sparQ uses SQLite (zero-config). To use PostgreSQL, set DATABASE_URL in your .env:

DATABASE_URL=postgresql://sparq:sparq@localhost:5432/sparq

Then start a Postgres container and run:

cd pulse
make db-start
make run

Configuration

Copy .env.example to .env in the pulse/ directory. The app auto-generates one on first run if missing.

Key settings:

See pulse/.env.example for the full list.

Server Admin Panel (MSA)

sparQ includes a built-in admin console at /msa for managing organizations, workspaces, and users. It is disabled by default. Set both MSA_USER and MSA_PASS in your .env to enable it.

Email Setup

sparQ sends transactional emails for signups, password resets, and magic link logins. Configure email from the admin panel or via environment variables.

Option 1: Admin Panel (recommended)

1. Enable the MSA admin panel (set MSA_USER and MSA_PASS)
2. Navigate to /msa/email
3. Select a provider (Gmail, Microsoft 365, SendGrid, Mailgun, AWS SES, or custom SMTP)
4. Enter your credentials and click Save Configuration
5. Use Test Connection and Send Test Email to verify

Option 2: Environment Variables

Set these in your .env to configure email without the admin panel:

Environment variables take priority over admin panel settings. Fields locked by env vars are shown with a lock icon in the admin panel.

Gmail users: Enable 2-Step Verification, then generate an App Password. Use the 16-character app password, not your regular password.

If no email provider is configured, signup falls back to direct password-based registration (no email confirmation).

GitHub Integration

sparQ syncs tasks and blockers with GitHub Issues. Connect using a classic Personal Access Token (PAT):

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Create a new token with these scopes: repo and admin:repo_hook
3. In sparQ, go to Settings → Integrations and paste your token and repository (owner/repo)
4. Open Settings → Integrations → GitHub → Match GitHub people and map each GitHub account to a sparQ member, so commit and PR activity is attributed to the right person (unmapped accounts are skipped). Members can also self-map in their own settings.

That's it. Issues, labels, and assignees sync between sparQ and your repository, and commits and pull requests show up in the Status feed as each person's current activity.

Self-hosting behind a reverse proxy? Set GITHUB_WEBHOOK_BASE_URL to your public URL (e.g. https://app.example.com) so the auto-registered webhook resolves correctly, and set GITHUB_WEBHOOK_SECRET to verify inbound webhooks (required in production).

Project Structure

sparq/
├── pulse/                  # Main application (sparQ Pulse)
│   ├── app.py              # Application factory
│   ├── modules/            # Feature modules (core, updates, presence, etc.)
│   ├── system/             # Framework (db, auth, email, middleware, etc.)
│   ├── tests/              # Unit, integration, and e2e tests
│   ├── Makefile            # Dev commands (make run, make venv, etc.)
│   └── requirements.in     # Python dependencies
├── metrics/                # (coming soon)
├── knowledge/              # (coming soon)
└── docker-compose.yml

Tech Stack

• Backend: Python, Flask, SQLAlchemy, Flask-SocketIO
• Database: SQLite (default) or PostgreSQL
• Frontend: Server-rendered Jinja2 templates, HTMX
• Real-time: WebSocket via Flask-SocketIO
• Production: Gunicorn

Development

cd pulse

# Run tests
python -m pytest tests/

# Reset database
make reset

# Verbose startup (shows module loading)
make run V=1

Contributing

We welcome contributions! Please read our Contributing Guide to get started.

If you find a security vulnerability, please follow our Security Policy instead of filing a public issue.

License

This project is licensed under the GNU Affero General Public License v3.0.

Copyright (c) 2025-2026 sparQ Software LLC.