Flick — Automated UX Bug Detection from PostHog Session Replays

Automatically find bugs in web applications by analyzing PostHog session replay data — without anyone having to watch a single replay. PostHog records user sessions as DOM snapshots (via rrweb). Flick pulls those snapshots, parses raw DOM state, network requests, navigation events, and console logs, then runs heuristic detectors and AI analysis to surface actionable issues with direct links to the exact moment in the replay where the bug occurred.

Features

• AI-Powered Issue Detection — Analyzes PostHog session replays to find rage clicks, dead clicks, error states, slow pages, form abandonment, navigation confusion, broken elements, and API failures
• 15 Heuristic Detectors — Content overflow, data transformation errors, redirect loops, payload bloat, waterfall delays, asset loading failures, skeleton persistence, DOM flicker, silent failures, and more
• Agentic Analysis — LLM agent with Gemini function calling that reads session timelines and takes targeted screenshots to visually verify bugs
• Embedded Replay Viewer — View the PostHog session replay directly alongside the issue details
• Severity Classification — Issues are classified as critical, high, medium, or low with auto-escalation by frequency
• Issue Deduplication — Same logical bug across sessions shares a fingerprint and groups into a single issue
• Review Queue — Human-in-the-loop approval workflow for detected issues before they go live
• Linear Integration — Create Linear issues directly from detected UX problems
• Slack Integration — Send notifications and critical alerts to Slack
• Multi-Project Support — Connect multiple PostHog projects

Tech Stack

Layer	Technology
Frontend	Next.js 16 (App Router), TypeScript, Tailwind CSS
Backend	Python 3.12, FastAPI, SQLAlchemy (async), Playwright
Database	Supabase Postgres
Auth	Supabase Auth
AI	Google Gemini (primary), Anthropic Claude (optional)
Observability	Sentry, Braintrust
Infrastructure	GCP Cloud Run, Terraform, Vercel

Quick Start

Prerequisites

• uv (Python package manager)
• Bun 1.x (frontend runtime)
• A Supabase project (database + auth)
• A Google Gemini API key (for AI analysis)
• A PostHog account with session recordings enabled

1. Clone and configure

git clone <repo-url> && cd flick

Create backend/.env:

DATABASE_URL=postgresql+asyncpg://postgres:[PASSWORD]@db.[REF].supabase.co:5432/postgres
SUPABASE_URL=https://[REF].supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
GEMINI_API_KEY=...
LLM_PROVIDER=gemini

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://[REF].supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

2. Start development

./flick start

This installs all dependencies and starts both services:

Service	URL	Description
Frontend	http://localhost:3000	Next.js web app
Backend	http://localhost:8000	FastAPI REST API

Press Ctrl+C to stop both.

3. Create an account

1. Open http://localhost:3000
2. Sign up with Supabase Auth
3. You'll be redirected to the dashboard

4. Connect PostHog

1. Go to Settings → New Project
2. Enter your project name and PostHog host (US or EU)
3. Enter your PostHog Personal API Key (read access to session recordings)
4. Enter your PostHog Project ID
5. Click Create Project

5. Analyze sessions

1. Go to the Issues dashboard
2. Select how many sessions to analyze
3. Click Analyze Sessions
4. Issues appear as they're detected

6. (Optional) Connect integrations

Linear: Settings → Linear section → add API key + Team ID

Slack: Settings → Slack section → add Incoming Webhook URL

Flick CLI

The flick script at the project root is the single entry point for development and deployment.

./flick start              # Install deps + start backend & frontend
./flick deploy             # Build, push, and deploy backend to Cloud Run
./flick deploy --skip-build  # Re-deploy existing image
./flick help               # Show all commands

On first clone, make it executable: chmod +x flick.

Project Structure

flick/
├── flick                         # Developer CLI (start, deploy)
├── frontend/                     # Next.js 16 (App Router)
│   ├── src/app/
│   │   ├── auth/                 # Login & signup
│   │   └── dashboard/            # Issues board, issue detail, settings, review queue
│   ├── src/components/           # Reusable UI components
│   └── src/lib/                  # API client, auth, utilities
├── backend/                      # Python FastAPI
│   ├── app/
│   │   ├── main.py               # FastAPI entry point
│   │   ├── models/               # SQLAlchemy models
│   │   ├── routers/              # API endpoints
│   │   ├── services/             # LLM client, PostHog client, Slack/Linear
│   │   └── workers/              # Session processing orchestrator
│   └── src/posthog_pipeline/     # Core analysis pipeline
│       ├── ingestion/            # Blob fetching, event parsing, session discovery
│       ├── extraction/           # Stream extraction (DOM, network, console, etc.)
│       ├── detection/            # 15 heuristic detectors + clustering
│       ├── rendering/            # Playwright + rrweb screenshot/video capture
│       ├── verification/         # LLM analysis, agentic analyzer, prompt building
│       └── filtering/            # Feedback rules, issue filtering
├── infra/                        # Terraform (GCP Cloud Run, secrets)
│   └── scripts/                  # deploy.sh, update-secret.sh
├── db/                           # Supabase migrations
└── docs/                         # OAuth, PostHog, pipeline documentation

How It Works

1. Session Discovery — Queries PostHog for recent completed sessions, filtering by duration, activity, and console errors. Excludes already-processed sessions.

2. Ingestion — Fetches rrweb snapshot blobs (DOM snapshots, incremental mutations) and PostHog query events (pageviews, clicks, rage clicks, exceptions, network requests) in parallel.

3. Extraction — Parses blob events into typed streams: DOM snapshots, navigation, interactions, network requests, console logs, errors, mutation log, and node registry.

4. Detection — 15 heuristic detectors run in parallel to produce findings: content overflow, data transformation errors, redirect loops, payload bloat, waterfall delays, asset loading failures, error DOM mutations, skeleton persistence, DOM flicker, silent failures, inactivity gaps, form state corruption, error page text, uncaught exceptions, and PostHog event signals.

5. Visual Verification — Findings are clustered by time proximity, screenshots are captured via Playwright + rrweb Replayer, and an LLM (Gemini) analyzes screenshots + context to confirm or dismiss each finding.

6. Issue Persistence — Confirmed issues are deduplicated via fingerprinting, grouped across sessions, auto-escalated by frequency, and stored with console/network context around the bug moment.

Detection Modes

Mode	Description
unified (default)	Full pipeline: extraction → 15 detectors → clustering → screenshots → LLM verification
llm_only	Skips detectors; sends event timeline directly to LLM
agentic	LLM agent with Gemini function calling; reads timeline, takes targeted screenshots, loops up to 3 times
event_centric	Investigates a specific custom event with before/after screenshots

Environment Variables

Backend

Variable	Required	Description
DATABASE_URL	Yes	Supabase Postgres connection string
SUPABASE_URL	Yes	Supabase project URL
SUPABASE_PUBLISHABLE_KEY	Yes	Validates bearer tokens via Supabase Auth
GEMINI_API_KEY	Yes	Google Gemini API key for AI analysis
LLM_PROVIDER	No	gemini (default) or anthropic
ANTHROPIC_API_KEY	No	Required if LLM_PROVIDER=anthropic
BRAINTRUST_API_KEY	No	Enables Braintrust tracing for LLM calls
CORS_ALLOW_ORIGINS	No	Comma-separated origins (default: http://localhost:3000)

Frontend

Variable	Required	Description
NEXT_PUBLIC_API_URL	No	Backend API URL (default: http://localhost:8000)
NEXT_PUBLIC_SUPABASE_URL	Yes	Supabase project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Yes	Supabase publishable key

Development

The recommended way to run locally is via the CLI:

./flick start

To run services individually:

# Backend
cd backend
uv venv .venv
uv pip install -r requirements.txt --python .venv/bin/python
.venv/bin/uvicorn app.main:app --reload --port 8000

# Frontend
cd frontend
bun install
bun run dev

Database

Apply migrations via the Supabase SQL editor or CLI:

# Initial schema
db/supabase/migrations/001_supabase_auth_db.sql

Deployment

Backend (GCP Cloud Run)

./flick deploy                # Build + push + deploy
./flick deploy --skip-build   # Re-deploy existing image

Frontend (Vercel)

1. Set Vercel Root Directory to frontend
2. Set environment variables:
   • NEXT_PUBLIC_API_URL=https://<backend-domain>
   • NEXT_PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
   • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
3. Update backend CORS_ALLOW_ORIGINS to include the Vercel domain

License

MIT