Show HN: An AI skill for filtering and reading Hacker Newsletter and others
A Codex skill that reads a configured Gmail newsletter by date or date range, feeds raw decoded text MIME parts to the model, and uses link-filtering instructions to produce reports. It includes a local read-only Gmail daemon and supports per-link feedback stored in browser localStorage and exported as JSON.
Notifications You must be signed in to change notification settings
Fork 0
Star 0
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
2 Commits
2 Commits
.agents/skills/email-reader
.agents/skills/email-reader
email_reader
email_reader
.env.example
.env.example
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
pyproject.toml
pyproject.toml
uv.lock
uv.lock
Repository files navigation
Codex skill for reading a configured Gmail newsletter and passing its raw decoded text MIME parts to the model. The skill contains a local read-only Gmail daemon as an implementation detail; users normally invoke the skill with a specific date or date range rather than interacting with the daemon directly.
The skill starts the daemon, requests all messages from the configured sender for the requested period, passes all decoded text/plain and text/html MIME parts to the model, and uses .agents/skills/email-reader/LINK_FILTERING_INSTRUCTIONS.md for report selection, formatting, and feedback collection.
Use with Codex
Invoke the skill with a date or date range:
$email-reader 2026-06-27 $email-reader 2026-06-01 2026-06-27
The skill runs .agents/skills/email-reader/scripts/fetch_messages.py, which returns message metadata and raw decoded text MIME parts. The model interprets those parts when composing the report; the fetcher does not select, clean, or rewrite their content. Generated reports keep per-link feedback in browser localStorage and can export it as Report.feedback.json for later preference updates.
Configure
Create .env in the project root:
[email protected] GMAIL_OAUTH_CREDENTIALS_PATH=gmail_client_secret.json HOST=127.0.0.1 PORT=4873
Get the OAuth client file:
Open https://console.cloud.google.com.
Create or select a project.
Enable APIs & Services -> Library -> Gmail API.
Configure Google Auth Platform -> OAuth consent screen -> Branding.
Add your Gmail account to test users if the app is in test mode.
Create Google Auth Platform -> Clients -> Create client.
Select application type Desktop app.
Download the JSON file.
Rename it to gmail_client_secret.json and put it in the project root.
This must be an OAuth client JSON for an installed desktop app. Do not use an API key or a service account JSON.
The scope in code is:
https://www.googleapis.com/auth/gmail.readonly
Local daemon
Install the locked dependencies first:
uv sync --locked
The daemon can also be started directly for local development:
UV_CACHE_DIR=/tmp/uv-cache uv run --locked python -m email_reader
On the first /messages request, the daemon opens the OAuth authorization URL in the default browser. Finish Google authorization; the local OAuth token is saved to .gmail_token.json. If Google rejects an old or revoked token, the daemon automatically starts authorization again and keeps the old token as a backup.
If Google shows Access blocked: this app has not completed the Google verification process, wait and try again later. It can take up to 24 hours for new OAuth app settings and test-user changes to become available.
The API is available at /messages:
curl 'http://127.0.0.1:4873/messages?start_date=2026-06-01&end_date=2026-06-27'
Resources
Readme
MIT license
Activity
Stars
0 stars
Watchers
0 watching
Forks
0 forks
Report repository