# StackStats — Full Reference

> StackStats is a local desktop analytics app for Substack newsletter writers. It reads your Substack CSV exports on your own machine and surfaces insights that Substack's native dashboard never shows: subscriber engagement segments, cohort retention, churn risk scores, superfan identification, content-to-growth correlation, open rate decay, and optimal posting times. No cloud, no subscription, no account required. One-time purchase.

## About StackStats

**What it is:** A local Electron desktop application (Mac and Windows) for Substack analytics.

**Current version:** v1.5.2 (released March 25, 2026)

**Website:** https://stackstats.app

**Live demo:** https://demo.stackstats.app (pre-loaded with real newsletter data)

**Built by:** Rishikesh Sharan (@rishikeshshari), a Substack writer publishing "10+1 Things" — a weekly curated links newsletter with ~3,000 subscribers. Built because Substack's own dashboard couldn't answer the questions he actually had.

**Key differentiators:**
- 100% local processing — subscriber data never leaves the user's machine
- No subscription, no SaaS, no accounts — one-time purchase
- Works offline — no internet required except for optional AI features
- Supports both Mac (Apple Silicon and Intel) and Windows (x64)
- Auto-Sync Beta: downloads all Substack data in one click from within the app

## Pricing

**1-Year License — $39**
- 1 device
- 1 year of updates and support
- App works forever after year 1 (perpetual license)
- Renewal optional: $29/year — discount never expires
- Buy: https://buy.stackstats.app/l/stackstats-1year

**Lifetime License — $79** (launch price; regular $129)
- Up to 3 devices
- Every future update, forever
- Lifetime priority support
- Buy: https://buy.stackstats.app/l/stackstats-lifetime

**Refund policy:** 14-day refund. Checkout via Gumroad (secure).

## Analytics Tabs

### 1. Overview
Full-picture dashboard loaded on launch.
- KPI cards: total subscribers, 30-day growth, open rate, top acquisition source, active readers (last 7d)
- Secondary KPIs (when email stats loaded): best open rate ever, power users, posts published, signups attributed to content
- Latest post callout: title, days since posted, open rate (color-coded), delivered count, likes
- Subscriber growth chart (30d/90d/All periods) with linear regression trend line overlay
- 90-day growth forecast callout: projected total, avg subs/month, trend direction vs prior 30 days
- Traffic sources donut chart
- Smart Insights panel (full-width, two-column): source quality insight, growth plateau detection, and other automated callouts

### 2. Growth Sources
Where subscribers actually come from — and what converts.
- Period filter: 7d / 30d / 90d / All
- Daily new subscribers line chart with trend line
- Daily visitors line chart
- Stacked area chart: visitor sources over time (top 6 sources, with matching legend colors)
- Source ranking table: each source ranked by conversion rate (new subscribers / visitors)
- Content-to-Growth Correlation table: shows subscriber lift before and after each post
- Source quality by engagement table

### 3. Subscribers
Full subscriber list analytics.
- 8 stat cards: total subscribers, active last 7d, unengaged count, countries reached, re-engage targets, deliverability risk, power users, median days since last open (color-coded green/yellow/red)
- Smart Audience Segments (Champions, New & Active, Loyalists, At Risk, Ghosts) — computed from tenure, engagement recency, and subscriber type
- Churn Risk Radar: each subscriber scored 0–100; High/Medium/Low distribution with CSV export per bucket
- Engagement donut chart
- Subscribers by country chart
- Acquisition sources breakdown
- Monthly new subscribers chart
- Free-to-paid conversion time histogram (if paid subscribers exist)
- Churn section (if cancellation data available)

### 4. Publications
Per-post analytics from your email sends.
- Publishing Health snapshot: open rate trend, all-time best post, best posting time
- 5 KPI cards: posts published, avg open rate, avg delivered, avg likes, total signups from content
- Best Day to Post chart (from your actual post history, with small-sample warnings)
- Best Hour to Post chart (same)
- Open rate trend over time
- Top Growth Posts table: which posts brought the most new subscribers
- Hidden Gems: posts with strong engagement scores but below-average open rates
- Resend Candidates: posts with high delivery but low open rate (good candidates to resend)
- Post-to-Unsubscribe Correlation: subscriber cancellations 7 days before/after each post
- Full post table: title, date, open rate, click rate, likes, comments, signups, engagement score
- Podcast episode chart (if applicable)

### 5. Deep Dive
Behavioral analytics requiring the subscriber export.
- 4 stat cards: superfans, power users, top reader engagement score, median subscriber tenure
- Engagement funnel (horizontal): delivered → opened → clicked → commented → shared
- Subscriber lifetime donut
- Engagement by subscriber tenure
- Opens distribution histogram
- Cohort retention chart: % of each monthly cohort with opens in last 30d (last 12 cohorts, color-coded green/yellow/red)
- Superfans widget: scored by comments×10 + shares×8 + clicks×5 + gifts×20
- Open rate decay chart: how open rates fall off as newsletters age
- Device breakdown (from ZIP export): opens by device type (mobile/desktop/tablet)
- Top 15 Most Engaged Readers table (with PII masking toggle, CSV export)
- Recoverable At-Risk Subscribers table (engaged in past, now quiet — CSV export)

### 6. Reach
Page views, followers, and geographic audience.
- KPI cards: total page views, peak day (or month for monthly-only data), avg daily/monthly views, total followers, follower growth
- Daily page views line chart
- Follower growth chart
- Top countries by subscriber signups (bar chart)
- Top US states/provinces by subscriber signups (bar chart)
- Top Countries by Email Opens (from ZIP export — % of total opens by country)
- Period filter: 7d / 30d / 90d / All

### 7. AI Insights (optional)
Requires an AI provider configured with your own API key (or Ollama for free/offline use).
- 4 insight cards generated on demand: Growth, Engagement, Audience, 30-Day Action Plan
- Live chat interface: ask questions about your specific newsletter data
- Example questions: "Which post drove the most new subscribers?", "Why did my open rate drop last month?", "What day of the week gets the best open rates?"
- Data sent to AI: aggregated summaries only — no raw subscriber PII
- Newsletter name from settings used in all AI prompts

## Supported AI Providers

| Provider | Models | Notes |
|---|---|---|
| Anthropic | Claude Sonnet, Haiku, Opus | Recommended |
| OpenAI | GPT-4o, GPT-4o mini | — |
| Google Gemini | Gemini 1.5 Flash, Pro | — |
| OpenRouter | Any model on OpenRouter | Single key, many models |
| Groq | Llama 3, Mixtral, Gemma | Fast inference, free tier |
| Ollama | Any local model | 100% offline, no API key |
| Custom | Any OpenAI-compatible endpoint | Set custom base URL |

## Data Import

**Auto-Sync (Beta):** One-click download of all Substack data directly from the app.
- Downloads 9 files total: traffic, followers, growth sources, audience (global + US states), email stats, traffic sources, subscriber export, ZIP export
- Requires Substack login (one-time, done in an in-app popup)
- ZIP export takes 2–5 minutes (background)

**Manual Download:** Export CSV files from Substack dashboard and point the app at the folder.
- Files auto-detected by column headers (not filename)
- Supported file types: subscriber export, email stats (ZIP), growth sources, traffic, traffic sources, followers, audience location (countries + US states)

**Required exports from Substack:**
1. ZIP export (Settings → Export data) — unlocks per-post open rates, clicks, device breakdown, geographic data
2. Subscriber export (Audience → 3 dots → Export all columns) — 43 columns including engagement history, country, activity
3. Growth sources (Growth → All time → Download CSV)
4. Audience location × 3 (Stats → Audience, World + USA + Followers)
5. Traffic (Stats → Traffic → Download CSV)
6. Traffic sources (Stats → Traffic → Traffic by source → Download CSV)

## Privacy & Data

- All newsletter data stays on the user's machine — never transmitted anywhere
- Only data sent externally: license key + device fingerprint (for license validation, over HTTPS to Cloudflare)
- No telemetry, no crash reports, no behavioral analytics
- AI keys stored locally only — never seen by StackStats
- If using AI: only aggregated summaries sent to the chosen provider (not raw subscriber data)
- Full privacy policy: https://stackstats.app/privacy
- GDPR compliant

## Licensing Model

**Perpetual license:** The app keeps working after the update period ends. No forced upgrades, no feature lockout.

**1-Year:** 1 device. After year 1, the app continues working on that version. Renew for $29/year (discount never expires) to get new updates.

**Lifetime:** Up to 3 devices. All future updates forever. Manage devices at https://stackstats.app/manage-license.

**License validation:** On launch, the app checks a Cloudflare Worker backend using the license key + device fingerprint. If offline and previously verified within 7 days, validation is cached (offline-safe).

Full licensing details: https://stackstats.app/license

## Installation

**Mac:**
- Apple Silicon (M1/M2/M3/M4): download StackStats-arm64.dmg
- Intel Mac: download StackStats-x64.dmg
- Drag to Applications; macOS may show a Gatekeeper warning (not code-signed yet) — go to System Settings → Privacy & Security → Open Anyway

**Windows:**
- Download StackStats-Setup.exe (x64)
- Windows SmartScreen may warn — click More info → Run anyway

**Updates:** Over-the-air (OTA). App checks for updates on every launch. Download and restart handled automatically.

Download links: https://stackstats.app (under Pricing / Download section)

## Technical Architecture

- Built with: Electron (Node.js main process + browser renderer)
- Charts: Chart.js v4
- CSV parsing: PapaParse
- No React, no Tailwind, no build step — vanilla JS + hand-written CSS
- AI: @anthropic-ai/sdk for Anthropic; openai npm package for all other providers
- Licensing backend: Cloudflare Worker + D1 (SQLite) database
- Distribution: Gumroad for payments; GitHub Releases for app binaries

## Key Computed Metrics (not available in Substack)

- **Engagement score** (per subscriber): opens×3 + clicks×5 + views×0.5 + comments×10 + shares×8, normalized 0–100
- **Superfan score**: comments×10 + shares×8 + clicks×5 + gifts×20
- **Churn risk score**: 0–100, based on engagement recency and decay (60-day grace period for new subscribers)
- **Smart Audience Segments**: Champions (high tenure + high engagement), New & Active, Loyalists (long-tenure, moderate engagement), At Risk (declining engagement), Ghosts (no recent activity)
- **Power users**: subscribers with 2+ of {links clicked, comments, shares, gifted subscriptions}
- **Re-engage targets**: subscribers who were active (opened/viewed/clicked) but have not opened in last 30 days
- **Cohort retention**: % of each join-month cohort still opening emails, last 12 cohorts
- **Content-to-Growth Correlation**: subscriber count delta in 7 days before vs after each post
- **90-day growth forecast**: based on last 30-day average vs prior 30-day average
- **Post engagement score**: composite 0–100 combining open rate, likes, comments, shares, and signups

## Contact & Links

- Website: https://stackstats.app
- Email: hello@stackstats.app
- Demo: https://demo.stackstats.app
- Twitter/X: https://x.com/rishikeshshari
- Discord: rishikeshs
- GitHub: https://github.com/rishikeshsreehari
- Product Hunt: https://www.producthunt.com/products/stackstats

StackStats is not affiliated with or endorsed by Substack Inc. Substack is a trademark of Substack Inc.