seo-digest

A weekly SEO and traffic digest for your website, delivered as plain markdown or straight to your inbox. No dashboard login required.

Most small business owners never open Google Analytics or Search Console. The data is there, but it lives behind two logins and a wall of charts. seo-digest pulls the numbers that matter once a week, compares them to the week before, and writes a short, readable summary: what you rank for, what is rising, how much search traffic you got, and where your visitors came from.

It is free, open source, read-only, and runs on your own machine or free on GitHub Actions.

• Reads Google Search Console (clicks, impressions, average position, rising queries)
• Reads Google Analytics 4 (users, sessions, top pages, traffic sources)
• Compares this week to last week and calls out the changes
• Writes a markdown file, and optionally emails it
• Works with either data source alone, or both together

---

What you get

# Corner Coffee - Weekly SEO & Traffic Digest

**Week of 2026-07-08 to 2026-07-14**, compared with the prior 7 days.

## Summary

- **Search clicks:** 1,240 (+18.2% vs last week)
- **Impressions:** 45,300 (+6.1%)
- **Average position:** 12.4 (improved 0.7)
- **Website users:** 980 (-3.0%)
- **Sessions:** 1,510 (+2.2%)

The full report adds a search-performance table, your top and rising queries, your best landing pages, GA4 traffic with week-over-week change, most-viewed pages, and traffic sources. See the complete example in examples/sample-digest.md.

---

Two ways to set it up

Option A: send your AI agent to do it

If you use an AI coding assistant (Claude Code, Cursor, Copilot, Codex, and similar), you do not have to set this up by hand. Point your agent at this repository and say:

"Set up seo-digest for my website and walk me through it."

This repo ships with an agent runbook (AGENTS.md) written for exactly that. Your agent installs the tool, guides you through the few clicks only you can do in your Google account, writes your config, runs a test, and can schedule it. Claude Code users can also run the /setup-seo-digest command.

Option B: do it yourself

git clone https://github.com/donebydefault/seo-digest.git
cd seo-digest
pip install -r requirements.txt
cp config.example.yaml config.yaml   # then edit it

Then follow AGENTS.md, which is a plain-language, step-by-step setup guide whether a human or an agent is reading it. The one-time setup is creating a Google "service account" (a read-only robot login), enabling two APIs, and granting it Viewer access to your data. It takes about ten minutes.

Once configured:

python -m seo_digest --check     # validate config + credentials, no API calls
python -m seo_digest --stdout    # preview the digest in your terminal
python -m seo_digest             # write digest.md
python -m seo_digest --email     # also send it (after configuring email)

---

Configuration

All non-secret settings live in config.yaml (copied from config.example.yaml):

site:
  name: "My Business"
  ga4_property_id: "123456789"              # or "" to skip GA4
  search_console_site: "sc-domain:example.com"   # or "" to skip Search Console
window:
  days: 7
  search_console_lag_days: 3
output:
  file: "digest.md"
email:
  enabled: false

Secrets are never stored in the config file or the repo. They come from environment variables:

Variable	Purpose
SEO_DIGEST_SERVICE_ACCOUNT	Path to your service-account .json key
SEO_DIGEST_SERVICE_ACCOUNT_JSON	The key's contents inline (used in CI)
SEO_DIGEST_SMTP_PASSWORD	Your SMTP password (only if email is on)

---

Schedule it weekly

• On a machine that is usually on: add python -m seo_digest --email to cron (macOS/Linux) or Task Scheduler (Windows), once a week.
• Without running a server: use the included GitHub Actions workflow at .github/workflows/weekly-digest.yml. It runs free on a schedule. Your config and both secrets are stored as encrypted repo Actions secrets and materialized only at run time, so nothing sensitive is ever committed. The comments at the top of that file have the exact steps.

---

FAQ

Is my data safe? The tool only ever reads. It uses read-only Google scopes, changes nothing in your account, and stores nothing off your machine. Your service-account key and any password stay in environment variables and are gitignored so they cannot be committed by accident.

Do I need both Google Analytics and Search Console? No. Either one alone works. Search Console is the most useful single source for SEO and is free to add to any site you own.

Why does Search Console lag a few days? Google finalizes Search Console data about three days late. The tool ends its Search Console window three days back so it compares complete data with complete data. Google Analytics is near-real-time.

Why is a query missing that I know I rank for? Search Console only reports queries that had impressions in the window, and its data has a delay. Give it a week of history.

---

Development

python -m pytest        # offline tests: date math, deltas, markdown rendering

The reporting logic in seo_digest/digest.py is pure (plain dicts in, strings out) and fully tested without network access. The Google API calls live in seo_digest/gsc.py and seo_digest/ga4.py.

---

License

MIT. See LICENSE.

---

Built by Done by Default. We build and run automations like this one for small businesses, so the busywork gets done without you in the loop. If you want a fleet of these set up and maintained for you rather than self-hosted, that is what we do.