InsightPulse

Stop writing weekly updates. Start shipping them.

Pulls a week of work from your tools, has an LLM write a structured email, sends it, logs it to Notion.

Install · Demo · Why? · CLI · Compare · Contribute

---

See it in 5 seconds

No setup, no API keys, no network. Just insightpulse demo.

pip install insightpulse
insightpulse demo      # sample data, shows what a real run looks like
insightpulse init      # interactive setup wizard
insightpulse run       # your first real weekly update

---

Why InsightPulse?

You write a Friday status email. Every week. It takes 2-3 hours of copy-pasting from Linear → GitHub → Notion into something coherent. Then you forget half of what shipped.

InsightPulse does it for you. It pulls this week's work from your tools, has an LLM write a structured email in your voice, sends it to your stakeholders, and logs the result as a Notion sub-page. The whole thing runs in 30 seconds.

	Without InsightPulse	With InsightPulse
Time per Friday update	2-3 hours	30 seconds
What you remember	Half of it	Everything
Tone	"I think we shipped some stuff"	Structured: shipped / at risk / next
Audit trail	Search your sent mail	Notion sub-page per week
Cost	$0 + your time	$0.50/mo (Groq free tier)

It's open source. No per-seat pricing, no vendor lock-in, no data leaving your control. Linear/GitHub/Notion/Slack data goes to an LLM (you pick the provider), gets redacted for secrets on the way out, and the resulting email + Notion log are yours forever.

---

Comparison

Most "weekly status update" tools are closed SaaS. InsightPulse is the open-source, self-hostable alternative.

	InsightPulse	Status Hero	Friday.app	Weekdone	15Five
Open source	✅ MIT	❌	❌	❌	❌
Self-hostable	✅	❌	❌	❌	❌
CLI-first	✅	❌	❌	❌	❌
No per-seat pricing	✅ (free)	$5/user/mo	$4/user/mo	$4/user/mo	$4/user/mo
Linear	✅	❌	❌	❌	❌
GitHub PRs	✅	❌	❌	❌	❌
Notion log	✅	❌	✅	❌	❌
LLM-synthesized	✅	❌	❌	❌	❌
Customizable output	✅ (greeting, sign-off, prompts)	❌	Limited	Limited	Limited
ICP lead scoring	✅ (bonus)	❌	❌	❌	❌

---

Install

pip install insightpulse

That's it. Python 3.11+, no other system dependencies. Works on macOS, Linux, Windows.

From source (for development):

git clone https://github.com/interfluve-wav/insightpulse.git
cd insightpulse
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,pandas]"

Docker:

docker build -t insightpulse:dev .
docker run --rm -p 8000:8000 \
  -e INSIGHTPULSE_API_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))") \
  -v $(pwd)/.env:/app/.env:ro \
  -v insightpulse-data:/data \
  insightpulse:dev

---

Quick start

# 1. See it work (no setup needed)
insightpulse demo

# 2. Set up for real
insightpulse init          # interactive wizard — picks LLM, sources, etc.

# 3. Run
insightpulse run --dry-run # synthesize without sending
insightpulse run --live-test # full pipeline, [TEST] markers
insightpulse run           # go live (email + Notion log)

# 4. Schedule it (cron, n8n, GitHub Actions — your choice)
0 9 * * FRI  cd /path && /path/.venv/bin/insightpulse run

That's the whole loop. 60 seconds from pip install to your first automated Friday email.

---

CLI

insightpulse demo                # see it work — no setup, no API keys
insightpulse init                # interactive setup wizard — create your .env
insightpulse run [--dry-run|--live-test]
                                 # full pipeline (aggregate → synthesize → email → log)
insightpulse status              # at-a-glance config + last run + health
insightpulse doctor              # validate env + probe each configured API
insightpulse history [--limit N] # see past runs
insightpulse init-log            # create the Notion log database
insightpulse serve               # start the web UI + API
insightpulse score-leads <csv>   # ICP lead scoring (offline; needs pandas)
insightpulse version              # print version

Run insightpulse --help for the full reference with examples.

---

HTTP API (additional surface)

The same pipeline, over JSON. insightpulse serve starts a FastAPI service at http://localhost:8000:

Method	Path	Auth	Description
GET	/	open	Web UI (single-page app, no build step)
GET	/health	open	Liveness probe
GET	/ready	open	Doctor readiness (503 if any source errors)
GET	/docs	open	OpenAPI / Swagger UI
POST	/runs	bearer	Trigger a pipeline run (returns 202, runs in background)
GET	/runs	bearer	History of past runs
GET	/runs/{period_key}	bearer	Full run details (subject, body, highlights, risks, sources)
GET	/runs/{period_key}/update	bearer	Rendered email (subject + body)
POST	/runs/{period_key}/resend	bearer	Re-send the email for a past run

The API token is read from INSIGHTPULSE_API_TOKEN. If unset, the server auto-generates a temporary one and prints it at startup.

---

Architecture

System flow

flowchart LR
    CLI[insightpulse<br/>run] --> P
    API[insightpulse<br/>serve :8000] --> P
    WebUI[Web UI<br/>/] --> API

    P[pipeline.py<br/>the engine]

    P --> N[Notion]
    P --> L[Linear]
    P --> G[GitHub]
    P --> S[Slack]
    P --> St[Stripe]

    N & L & G & S & St --> LLM

    subgraph synthesis [LLM synthesis]
        LLM[Groq / Fireworks<br/>/ Mistral]
        Risk[Risk pre-extract<br/>optional]
        Redact[redact.py<br/>secret scrub]
    end

    LLM --> Resend[Resend<br/>email send]
    LLM --> NotionLog[Notion log<br/>sub-page]
    LLM --> State[(SQLite<br/>state.db)]

Loading

Module layout

flowchart TB
    CLI[cli.py<br/>9 subcommands] --> Pipeline[pipeline.py<br/>run_pipeline]
    API[api.py<br/>FastAPI + UI] --> Pipeline
    Init[init.py<br/>wizard] -.-> CLI
    Demo[demo.py<br/>no-setup] -.-> CLI

    Pipeline --> Agg[data_aggregator.py<br/>5 fetchers]
    Pipeline --> LLM[llm_synthesizer.py<br/>parse + risk]
    Pipeline --> State[state.py<br/>SQLite]
    Pipeline --> Mail[gmail_client.py<br/>Resend / SMTP]
    Pipeline --> Notion[notion_logger.py<br/>sub-page]
    Pipeline --> Redact[redact.py<br/>secret scrub]

    Agg --> Sources[Notion / Linear<br/>/ GitHub / Slack / Stripe]
    LLM --> Providers[Groq / Fireworks<br/>/ Mistral]
    Mail --> Email[Resend / Gmail]
    Notion --> LogPage[Notion log DB]

Loading

Data flow for one run

sequenceDiagram
    autonumber
    actor User
    participant CLI
    participant Pipeline
    participant Doctor
    participant Agg
    participant LLM
    participant State
    participant Email as Resend
    participant Notion

    User->>CLI: insightpulse run
    CLI->>Pipeline: run_pipeline()
    Pipeline->>Doctor: run_doctor() (optional preflight)
    Pipeline->>Agg: aggregate(config)
    Agg->>Agg: fetch_notion/linear/github/slack/stripe
    Agg-->>Pipeline: AggregatedData
    Pipeline->>LLM: synthesize(data, extracted_risks)
    LLM-->>Pipeline: SynthesizedUpdate
    Pipeline->>Pipeline: redact_secrets(output)
    Pipeline->>State: mark_started(period_key)
    Pipeline->>Email: send_email(subject, body)
    Pipeline->>Notion: log_to_notion(subject, highlights, ...)
    Notion-->>Pipeline: page_id
    Pipeline->>State: mark_completed(period_key, ...)
    Pipeline-->>CLI: result dict
    CLI-->>User: Subject + body printed

Loading

One file per concern:

• cli.py — subcommands (CLI is the primary surface)
• api.py — FastAPI + web UI
• pipeline.py — the shared engine both call into
• data_aggregator.py — per-source fetchers
• llm_synthesizer.py — LLM call + parser + risk pre-extract
• redact.py — secret / PII scrubbing (defense in depth)
• state.py — SQLite state store (idempotency, history)
• doctor.py — env + per-source health checks
• models.py — dataclasses (WorkItem, TeamMetrics, SynthesizedUpdate)

---

Source integrations

Source	What it pulls	Required
Notion	Recently edited pages (14-day rolling window)	optional
Linear	Completed + in-progress issues	optional
GitHub	Merged PRs (per-repo or org)	optional
Slack	#wins + #blockers messages	optional
Stripe	Active subscriptions → MRR	optional

Configure only the tools your team uses. Missing sources just contribute 0 items to the synthesis prompt.

Sensitive-content filter on the Notion source: pages whose titles match common secret patterns (api key, secret, bearer, connection string, endpoint url, etc.) are dropped before the LLM sees them. Plus insightpulse.redact scrubs the LLM's output for credential formats + PII before it's persisted or sent.

---

ICP lead scoring (bonus)

A bonus feature, included because the same ICP model is useful for sales/marketing teams:

# Score any lead CSV
insightpulse score-leads data/leads.csv

Two dataset formats supported, auto-detected:

• yhat 100k (default) — attended_webinar, company_size, industry, etc.
• Kaggle 9.2k (Lead Scoring X Education) — Lead Origin, Lead Quality, etc.

Output: tier assignment (Enterprise / Mid-Market / SMB), top-10 outreach list, and a sample email draft.

---

Documentation

• Quick start — start here
• CLI reference — every command
• HTTP API — /docs after running insightpulse serve
• CHANGELOG.md — release history
• CONTRIBUTING.md — how to contribute
• SECURITY.md — threat model + reporting
• API_KEYS.md — where to get each key
• Makefile — make test, make lint, make serve, make docker-run

---

License

MIT © Suhaas — see LICENSE.

This project is not affiliated with Linear, GitHub, Notion, Stripe, Slack, Groq, Fireworks, Mistral, or Resend. All trademarks belong to their respective owners.

---

⭐ Star this repo if InsightPulse saves you time. It helps others find it.

💖 Sponsor on GitHub Sponsors if you want to support ongoing development.