Clone the Template.
Launch Your Own Cast.

MikeCast is a fully-automated pipeline that runs every weekday morning, pulling from a dozen news sources, scoring articles with GPT-4o, generating a polished email briefing and a conversational podcast episode — then delivering everything automatically with zero manual intervention.

End-to-end architecture — from raw RSS feeds to your podcast app

Once you've cloned the repo, use Claude Code to orient yourself before making any changes:

Everything listed below is free or has a generous free tier. You only need your local machine for the initial setup step — after that, everything runs in the cloud.

Verify your local environment is ready before continuing:

MikeCast organizes content into categories. Each category pulls from one or more sources. GPT-4o scores every article 1–100 for relevance, so you don't need to curate manually — just pick categories that match your interests and the scoring layer handles the rest.

Pick 3–5 categories to keep your briefing focused and your OpenAI costs low.

Built-in Free Sources (no API key required)

API-Key Sources

Customizing your topics with Claude Code

Adding a new category is a one-prompt job. The script follows a consistent pattern — Claude Code can read it and match that pattern exactly:

To bias the scoring toward companies or topics you care about most:

Fork the MikeCast template on GitHub (or clone it locally to customize before pushing). The repo is structured so that data/ is the only directory the Actions workflow writes to — everything else is source code.

1. Fork or clone

# Option A: clone and push to your own new repo
git clone https://github.com/schwim23/mikecast-starter.git
cd mikecast

# Option B: use GitHub's template feature
# → github.com/schwim23/mikecast-starter → "Use this template" button

2. Repository structure

Key files and directories in the MikeCast repo

The data/ directory is created automatically the first time the script runs (DATA_DIR.mkdir(exist_ok=True) runs at module load). You don't need to create it manually.

Let Claude Code generate the supporting files so you don't have to write them from scratch:

Never commit API keys to your repository. GitHub Secrets encrypts them and injects them as environment variables at runtime — your keys are never visible in logs.

How to add a secret

1. Go to your repo on GitHub → click Settings (top nav)
2. In the left sidebar, click Secrets and variables → Actions
3. Click New repository secret
4. Enter the secret name (exactly as shown in the table below) and paste the value
5. Click Add secret — repeat for each secret

Required secrets

Add startup validation so the script fails immediately with a clear message if any secret is missing, rather than crashing mid-run:

mikecast_briefing.py is a single-file script that orchestrates the entire pipeline. Here's what each major function does:

Customizing the script

All the key configuration lives at the top of the file. Use these prompts to make common customizations without needing to read through the full script:

# ── Configuration ─────────────────────────────────────────
PODCAST_VOICE     = "onyx"         # OpenAI TTS voice
PODCAST_MAX_WORDS = 750            # ~5 min at normal speech pace
TOP_ARTICLES      = 25             # stories per briefing
DEDUP_DAYS        = 7              # skip stories seen recently
SCORE_MODEL       = "gpt-4o"       # model for scoring
WRITE_MODEL       = "gpt-4o"       # model for writing

CATEGORIES = {
    "AI & Tech": [
        {"type": "rss",  "url": "https://hnrss.org/frontpage"},
        {"type": "rss",  "url": "https://techcrunch.com/feed/"},
        {"type": "rss",  "url": "https://feeds.arstechnica.com/arstechnica/index"},
    ],
    "Business & Markets": [
        {"type": "rss",  "url": "https://www.cnbc.com/id/100003114/device/rss/rss.html"},
    ],
    "NY Sports": [
        {"type": "rss",  "url": "https://www.espn.com/espn/rss/nfl/news"},
    ],
}

Your podcast needs a cover image — Apple Podcasts requires at least 1400×1400 px. Rather than using design software, generate it programmatically with Python's Pillow library. This keeps everything version-controlled and reproducible.

The PIL approach

Here's the pattern every asset script in this project follows — useful context if you want to write your own:

from PIL import Image, ImageDraw, ImageFont
import os

W, H = 1400, 1400
img = Image.new("RGB", (W, H), (13, 17, 23))   # #0d1117
draw = ImageDraw.Draw(img)

# Blue accent bar at top
draw.rectangle([0, 0, W, 100], fill=(79, 142, 247))

font_lg = ImageFont.truetype("/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf", 130)
font_sm = ImageFont.truetype("/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf", 62)

draw.text((W//2, 700), "MikeCast", fill=(230, 237, 243), font=font_lg, anchor="mm")
draw.text((W//2, 870), "Daily AI News Briefing", fill=(139, 148, 158), font=font_sm, anchor="mm")

img.save("assets/cover-art.png")

The .github/workflows/briefing.yml file tells GitHub to run your script automatically every weekday morning. It also commits the generated files (audio, HTML, feed.xml) back to the repo so they're served by GitHub Pages.

The 7-step Actions pipeline that runs every weekday at 6:45 AM ET

Full workflow file

name: Daily MikeCast Briefing

on:
  schedule:
    - cron: '45 11 * * 1-5'   # 6:45 AM ET on weekdays (UTC-5 in winter)
  workflow_dispatch:          # also allows manual trigger from Actions tab

jobs:
  briefing:
    runs-on: ubuntu-latest
    permissions:
      contents: write           # required so the job can git push

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - run: pip install -r requirements.txt

      - name: Generate briefing
        env:
          NYTAPIKEY: ${{ secrets.NYTAPIKEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GMAIL_APP_PASSWORD: ${{ secrets.GMAIL_APP_PASSWORD }}
          GMAIL_FROM: ${{ secrets.GMAIL_FROM }}
          GMAIL_TO: ${{ secrets.GMAIL_TO }}
        run: python mikecast_briefing.py

      - name: Commit & push data
        run: |
          git config user.name "MikeCast Bot"
          git config user.email "actions@github.com"
          git add data/ briefing_history.json
          git diff --staged --quiet || \
            git commit -m "briefing $(date +%Y-%m-%d)"
          git push

Key notes

• UTC offset: GitHub Actions cron uses UTC. In winter (EST = UTC-5), 11:45 UTC = 6:45 AM ET. In summer (EDT = UTC-4), change to 10:45 UTC for the same local time.
• workflow_dispatch: Lets you trigger the workflow manually from the Actions tab — useful for testing or backfilling a missed day.
• permissions: contents: write: Without this, the job cannot push commits back to the repo.
• Free tier limits: GitHub Actions gives 2,000 minutes/month on free accounts. Each MikeCast run takes ~2–3 minutes, so ~20 weekday runs/month ≈ 50 minutes — well within the free limit.

Before your first real run, have Claude Code audit the workflow file for common mistakes:

GitHub Pages turns your repo into a full static website — no separate hosting, no build pipeline, no cost. Everything your daily script commits to main is instantly live at your public URL. That includes the podcast dashboard, the RSS feed, the audio files, and the cover art.

One push to main → your entire site updates automatically

Your complete static site

After enabling Pages, every file in your repo has a permanent public URL. Here's what each one does:

Enable GitHub Pages

1. Go to your repo → Settings → Pages (left sidebar)
2. Under Source, select Deploy from a branch
3. Branch: main, Folder: / (root) → click Save
4. Wait ~60 seconds, then your site is live at https://YOUR-USERNAME.github.io/REPO-NAME/

Your feed URL

https://YOUR-USERNAME.github.io/REPO-NAME/data/feed.xml

# Example:
https://schwim23.github.io/mikecast/data/feed.xml

iTunes tag checklist

• Cover art URL in <itunes:image href="..."> — must be PNG or JPEG, ≥ 1400×1400 px
• <itunes:author> — your name or show name
• <itunes:category text="Technology"> — pick from Apple's category list
• <itunes:explicit>false</itunes:explicit>
• <itunes:owner> with <itunes:email> — your email for Apple to contact you
• Each <item> has <enclosure url="..." type="audio/mpeg" length="...">

Once you have at least one episode, use Claude Code to audit the feed before submitting to Apple:

Apple Podcasts Connect is the portal for submitting your show. Once approved (usually 24–72 hours), your podcast appears in search results in Apple Podcasts and is automatically syndicated to many other apps that use the Apple Podcasts directory.

1. Go to podcastsconnect.apple.com and sign in with your Apple ID
2. Click + → Add a Show → RSS Feed
3. Paste your GitHub Pages feed URL → click Validate
4. Review the parsed metadata — fix any red errors before proceeding
5. Set: Category (e.g. Technology), Language, Update Frequency (Daily)
6. Check: "I own or have rights to distribute all content in this podcast"
7. Click Submit — review takes 24–72 hours
8. Once approved, you'll receive your Apple Podcasts show URL to share

Common pitfalls

If the validator says your cover art is unreachable, this prompt diagnoses the root cause in the script:

Spotify for Podcasters is simpler than Apple Podcasts — it verifies ownership via a code sent to the email in your feed's <managingEditor> tag. Most shows go live within a few hours.

1. Go to podcasters.spotify.com → click Get Started
2. Choose I have an existing podcast → paste your RSS feed URL → click Next
3. Spotify sends a verification code to the email in <managingEditor> — enter it to verify ownership
4. Fill in: Country, Language, Audience, Category
5. Click Submit — your show should be live within a few hours

The managingEditor tag is easy to overlook. Check it before submitting:

If something's not working, check the GitHub Actions tab in your repo first — it shows full stdout/stderr for every run. Click the failed job → expand each step to find the error. Then paste it into Claude Code:

Common issues

Debugging specific components

Testing locally before deploying

# Install dependencies
pip install -r requirements.txt

# Set environment variables (never commit these!)
export NYTAPIKEY="your-nyt-key"
export OPENAI_API_KEY="sk-..."
export GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"
export GMAIL_FROM="you@gmail.com"
export GMAIL_TO="you@gmail.com"

# Run the script
python3 mikecast_briefing.py

# Serve locally to preview the output
python3 -m http.server 8080
# open http://localhost:8080 in browser