Daily Briefing Agent

Wake up to an AI-written news briefing in your inbox every morning, on the topics you choose, written from real freshly-searched articles.
100% free, no server, runs entirely on GitHub Actions.

A real briefing. Every headline, summary and link in it was chosen and written by the agent.

It's 8am. Your coffee is still too hot to drink, so you open your inbox, and the only
thing worth reading is already there. Three stories that actually matter to you, four
sentences each, every source linked and dated. Nothing you were sent yesterday. No feed,
no notifications, no twenty tabs you'll never get back to.

While you were asleep, an agent searched the web on your topics, threw out the filler,
read what was left and wrote it up. By the time your coffee is drinkable, you're caught
up, and you close the tab and get on with your day.

Try it in 2 minutes

You need two free API keys. No Gmail, no deploy, no account anywhere else.

git clone https://github.com/tballochi/daily-briefing.git
cd daily-briefing
pip install -r requirements.txt

python main.py --setup      # asks for your keys and checks each one works
python main.py --dry-run    # builds a real briefing, sends nothing

Both keys are free: Groq and
Tavily. Prefer not to use the wizard? Put them in a .env
file yourself as GROQ_API_KEY= and TAVILY_API_KEY=.

--dry-run researches the news, writes the briefing, prints it to your terminal and
saves the rendered email to data/preview.html. It sends nothing and stores nothing,
so you can see exactly what you'd be getting before setting up delivery.

Then edit config.yaml to your own topics and run it again.

What it actually does

Every morning, an autonomous agent:

1. Researches. Runs live web searches across your topics, judges the results, and
   skips anything it already sent you on a previous day.
2. Writes. Summarises the chosen stories from their real source text. No
   hallucinated facts, no fabricated links: every URL comes from a real search result.
3. Delivers. Emails you a newspaper-style digest, at the time you choose.

It's a tool-using agent, not a fixed script: it decides what to search, judges what's
worth keeping, and searches again if the results are thin.

In the email: your N top stories, each with a factual summary, source and publication
date · a word of the day · a quote of the day. Optionally, one slot is reserved for a
focus theme you never want to miss.

Make it yours: config.yaml

One readable file, no code, no secrets:

title: Daily Briefing        # shown in the email subject + header
num_articles: 3              # how many stories per morning

topics:                      # what the agent researches (free text)
  - AI & LLMs (GPT, Claude, agents, MCP)
  - automation & no-code (n8n, Zapier, Make)
  - dev tools & open source

focus:                       # OPTIONAL: a story that's ALWAYS included
  label: shipping / maritime / logistics
  priority_query: CMA CGM    # searched first; preferred when there's fresh news
  keywords: [cma cgm, shipping, maritime, container, freight]

model: openai/gpt-oss-120b   # the Groq model the agent thinks with
model_fallbacks:             # tried in order if the one above is retired
  - openai/gpt-oss-20b
  - qwen/qwen3.8-27b

Topics are free text, so point it at finance, climate, football, your industry, whatever
you want to wake up informed about. Don't want a guaranteed story? Delete the focus:
block. No config.yaml at all? Sensible defaults keep it running.

Deploy free on GitHub Actions

Nothing stays on. No server, no container, no cron on your laptop.

1. Click Use this template
to get your own copy (or fork it). Then clone it and run:

python main.py --setup

The wizard asks for each key, verifies it against the real API before saving, so a wrong
Gmail App Password fails here instead of silently at 8am tomorrow. It clears the inherited
de-duplication history, offers to upload your secrets with the gh CLI, and prints your
pinger URL with your repo already filled in.

2. Add 5 Settings → Secrets and variables → Actions secrets (the wizard can do
this for you if you have the gh CLI):

3. Test it now: Actions → Daily Briefing → Run workflow, tick force.

4. Make it punctual by adding a free external pinger (5 minutes, one time):

GitHub's own schedule: cron is unreliable on low-activity repos: it drops most
triggers and can fire hours late, so "before 10am" isn't guaranteed by it alone. The fix,
still 100% free, is a tiny external cron that calls GitHub at a fixed time. GitHub's own
cron stays on as a best-effort backup.

a) Create a GitHub token at new fine-grained token

• Repository access: Only select repositories → this repo
• Permissions → Actions: Read and write
• Copy the github_pat_... value

b) Create a free job on cron-job.org, daily at ~08:00 in your
timezone:

• Method: POST
• URL: https://api.github.com/repos/<you>/daily-briefing/actions/workflows/daily-briefing.yml/dispatches
• Body: {"ref":"main"}
• Headers:
  • Accept: application/vnd.github+json
  • Authorization: Bearer <your github_pat_...>
  • X-GitHub-Api-Version: 2022-11-28

A successful call returns HTTP 204. The pinger fires without forcing, so it still
passes the morning-window and once-a-day guards, so it can never double-send.

Renamed the repo later? Update the URL by hand; GitHub redirects GETs but not
reliably POSTs.

Design choices

The things this does differently, and what they cost:

FAQ

Nothing. A run uses a handful of Groq calls and up to 6 Tavily searches, well inside both
free tiers (Tavily gives 1000 searches/month; the briefing uses ~180). GitHub Actions is
free for public repos. cron-job.org is free. There is no paid tier to graduate into.

Your keys live in your GitHub repo's Actions secrets (or your local .env, which is
gitignored). The agent talks only to Groq, Tavily and Gmail's SMTP server. Nothing is
sent anywhere else, and the author never sees your keys, topics or briefings.

Edit model: in config.yaml to any model your Groq key can reach, and list backups
under model_fallbacks:. You can also override it without editing the file by setting
the GROQ_MODEL environment variable (or a GROQ_MODEL GitHub Actions variable).
Providers retire models regularly, so check
Groq's deprecations page for what's live.

Yes, with a small edit. email_sender.py uses plain smtplib over SSL, so pointing
SMTP_HOST / SMTP_PORT at another provider (Fastmail, Zoho, a company relay) and using
that account's credentials works. Gmail is the default only because its App Passwords are
free and easy.

Yes. The time is set by your cron-job.org job; the workflow only enforces a
06:00–11:00 Europe/Paris safety window so a stray trigger can't email you at night.
To move outside that window, edit the hour list in the gate step of
.github/workflows/daily-briefing.yml (and TIMEZONE in scheduler.py for local runs).

It retries once after two minutes. If that also fails you get a short "couldn't send
today" email explaining why, the full traceback goes to the Actions log, and the run is
marked failed, so a broken morning is red in the Actions tab rather than a green check.
The next morning's run is unaffected.

Set num_articles: to whatever you like. One briefing per day is enforced by design,
because the de-duplication history keys on the date, so a second daily send would need that
guard changed.

Run it locally instead

python main.py --setup    # guided setup (or copy .env.example by hand)
python main.py --dry-run  # preview only, sends nothing
python main.py --now      # build & send one briefing now
python main.py            # run the scheduler (daily at 09:00 Europe/Paris)

Tests

pip install -r requirements-dev.txt
pytest -q

Mocked network, no API keys needed, runs in under a second. Covers the model fallback
chain, config defaults, de-duplication and both send guards. CI runs it on every push.

Tech stack

Project structure

daily-briefing/
├── config.yaml            # your preferences: title, topics, focus, model
├── config.py              # loads/validates config.yaml, checks required secrets
├── main.py                # entry point (--setup / --dry-run / --now)
├── setup_wizard.py        # guided setup, verifies every key
├── agent.py               # the agent: research loop, writing, HTML rendering
├── email_sender.py        # Gmail delivery
├── scheduler.py           # the briefing jobs + local daily scheduler
├── history.py             # remembers sent articles (no repeats)
├── data/history.json      # the de-duplication memory
├── docs/                  # screenshot + sample briefing
├── tests/                 # pytest suite (no network)
└── .github/workflows/     # daily-briefing.yml (the morning run) + ci.yml

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.

Built by Timoté Ballochi.