redlens

A local lens on public Reddit history — archive users and topics, analyze them, own the data.

redlens.dev · How It Works · Install · Commands · Design

_{The serve coordinated-network view on a synthetic astroturf network — not real data.}

Archive and analyze public Reddit history, locally. redlens pulls from arctic-shift — a free, keyless mirror — and keeps everything in one SQLite file you own. No API keys, no setup, no Reddit account.

How It Works

Archive    redlens sync <user>     a user's full public post + comment history
           redlens track <topic>   build a subreddit net, archive every match
Analyze    redlens show / topics   rollups, scores, per-subreddit totals
Network    redlens serve           the coordinated-network dashboard (matrix, brands, seeding)
Render     redlens page <topic>    a standalone, dependency-free HTML report
           redlens report          bake the network dashboard into one shareable HTML file

arctic has no global text search, so a topic isn't a query — it's a net. track discovers the subreddits a topic lives in, archives every matching post across them, and remembers the net so re-runs pull only what's new. The schema is created and migrated automatically on first use. Full architecture and configuration in DESIGN.md.

Install

pip install -e ".[dev]"

Two runtime dependencies (platformdirs, sqlmodel), all permissively licensed (MIT/BSD/PSF).

Commands

Run redlens <command> --help for flags. track takes --query/--exclude keyword steering, --sources to pick the discovery net (name, global, web, popular, llm), --comments to archive threads, and --discover to widen the net through matched authors.

Explore the network live with serve, then hand off a static copy anyone can open:

redlens serve --cohorts cohorts.csv --brands brands.csv   # live localhost dashboard
redlens report --cohorts cohorts.csv -o network.html      # same view, one shareable file
redlens report --cohorts cohorts.csv --anon -o public.html  # same file, accounts pseudonymized

Optional LLM Key

An optional OpenAI-compatible API key powers redlens summarize, LLM-scored sentiment in page --summary, and the llm discovery source. The first interactive run offers to collect it, or run redlens setup anytime. It's stored mode-600 in your per-user config dir — details in DESIGN.md.

No Reddit official-API integration. As of late 2025 Reddit gates its API behind pre-approval and no longer hands out keys on request, so redlens relies on the keyless arctic-shift mirror. Hold Reddit credentials and want fresh sync? Open an issue and we'll build the provider around your key.

More

• DESIGN.md — architecture, configuration, data layout
• CONTRIBUTING.md — dev setup, releases (tag-driven, PyPI trusted publishing)
• CHANGELOG.md — release history
• SECURITY.md — reporting vulnerabilities