📣 Pheme

A self-hosted AI news scheduler powered by Google Gemini.

Pick the topics you care about, choose a time, and Pheme delivers a grounded daily digest — to your terminal, a file, or your inbox. Your keys, your machine, your data.

---

In Greek myth, Pheme was the goddess of fame, rumour, and report — the voice that carried news across the world. This Pheme does the same, on a schedule, for whatever you ask it to watch.

Why Pheme?

Most "AI news" tools are someone else's SaaS, holding your interests and your inbox hostage. Pheme is the opposite:

• 🔑 Bring your own key — runs entirely on your Google Gemini API key. No middleman, no account, no telemetry.
• 🌐 Actually grounded — every digest is built from live Google Search results via Gemini, with real source links. No hallucinated headlines.
• ⏰ Set-and-forget scheduling — define feeds once; Pheme delivers them every day at the time you choose.
• 🚨 Smart alerts — flag watch-terms (e.g. "interest rates", "my company") and Pheme highlights breaking matches.
• 📬 Deliver anywhere — pretty terminal output, Markdown/HTML files, or styled email. Mix and match per feed.
• 🧩 Fully local & open source — config and keys live in ~/.pheme, nothing leaves your machine except the Gemini API call.

Quickstart

# 1. Install (from source for now — npm package coming)
git clone https://github.com/lachydotmcg/pheme.git
cd pheme
npm install
npm run build
npm link            # makes the `pheme` command available globally

# 2. Set up your Gemini API key (free from Google AI Studio)
pheme init

# 3. Create your first feed
pheme add

# 4. Test it right now
pheme run my-feed

# 5. Let it run on schedule
pheme start

Get a free API key at aistudio.google.com/apikey. The free tier is generous enough for several daily feeds.

How it works

                ┌──────────────┐   topics + schedule
   pheme add ──▶│  ~/.pheme/   │◀───────────────────────┐
                │  config.json │                         │
                └──────┬───────┘                         │
                       │ feed                            │
                       ▼                                 │
   pheme start ──▶ ⏰ Scheduler ──▶ 🤖 Gemini + Google Search
                       │                     │
                       │                     ▼
                       │            grounded digest (JSON)
                       ▼                     │
                  📤 Delivery ◀──────────────┘
                   ├─ 🖥  terminal
                   ├─ 📄 file (md / html)
                   └─ ✉️  email (SMTP)

1. You describe a feed: some topics, a delivery time, a tone, and where it should go.
2. At the scheduled time (or on pheme run), Pheme asks Gemini to search the live web for the most important recent stories on those topics.
3. Gemini returns a structured digest with summaries and real source URLs.
4. Pheme renders it and delivers to every channel you configured.

Commands

Command	What it does
pheme init	Set up your API key, model, and optional email (SMTP) delivery
pheme add	Create a new feed (interactive wizard)
pheme list	Show all feeds, schedules, and delivery targets
pheme run <id>	Generate & deliver a feed right now (great for testing)
pheme run --all	Run every enabled feed once
pheme start	Start the always-on scheduler
pheme enable <id> / disable <id>	Toggle a feed without deleting it
pheme remove <id>	Delete a feed
pheme config	Show current config (secrets masked)

Example feed

A feed you might create with pheme add:

{
  "id": "morning-tech-brief",
  "name": "Morning Tech Brief",
  "topics": ["AI model releases", "semiconductor supply chain", "ASX tech stocks"],
  "cron": "0 7 * * *",          // every day at 7:00 AM, local time
  "tone": "briefing",
  "maxStories": 8,
  "lookbackHours": 24,
  "alertKeywords": ["acquisition", "outage"],
  "delivery": {
    "terminal": true,
    "file": { "dir": "~/pheme-digests", "format": "md" },
    "email": { "to": ["me@example.com"] }
  }
}

Email delivery

Pheme sends via plain SMTP, so it works with Gmail, Fastmail, SendGrid, Postmark, your own server — anything. Configure it during pheme init, or with environment variables:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password      # use an App Password, not your login password
SMTP_FROM="Pheme <you@gmail.com>"

Gmail tip: enable 2FA and create an App Password — your normal password won't work over SMTP.

Running it 24/7

pheme start blocks and fires feeds at their scheduled times. To keep it alive, run it under a process manager:

# pm2
pm2 start "pheme start" --name pheme

# systemd, Docker, or Windows Task Scheduler also work well.

Prefer not to run a daemon? Skip pheme start entirely and instead let your OS scheduler call pheme run --all on a cron / Task Scheduler trigger.

Configuration & privacy

• All settings live in ~/.pheme/config.json (override the location with PHEME_HOME).
• The file is written with 0600 permissions because it can hold your API key and SMTP password.
• Environment variables (or a local .env) always override the saved config — handy for servers and CI. See .env.example.
• Pheme makes exactly one outbound connection: to the Google Gemini API. There is no Pheme backend, no analytics, nothing phoning home.

Models & cost

Pheme defaults to gemini-2.5-flash — fast, cheap, and grounded with Google Search. Switch to gemini-2.5-pro per your config for deeper analysis. Each digest is a single grounded request, so a handful of daily feeds comfortably fits within Google AI Studio's free tier for personal use.

Roadmap

• Publish to npm (npm i -g pheme-cli)
• OAuth sign-in via Google AI Studio (in addition to API keys)
• Per-feed source allow/deny lists
• Webhook / Slack / Discord delivery
• Digest history & dedupe across runs
• A hosted dashboard (separate project) for those who'd rather not self-host

Contributing

Issues and PRs welcome. This is the open-source core — keep changes focused, typed, and dependency-light. Run npm run typecheck before opening a PR.

License

MIT © lachydotmcg