{"id":51251393,"url":"https://github.com/heurema/herald","last_synced_at":"2026-06-29T07:02:07.601Z","repository":{"id":340534000,"uuid":"1166456063","full_name":"heurema/herald","owner":"heurema","description":"Daily curated news digest for your domain. Claude Code plugin. Zero API keys, fully local.","archived":false,"fork":false,"pushed_at":"2026-03-29T11:05:17.000Z","size":2164,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T13:59:21.777Z","etag":null,"topics":["ai-agent","anthropic","claude","claude-code","claude-code-plugin","news-digest","rss"],"latest_commit_sha":null,"homepage":"https://skill7.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heurema.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T08:42:13.000Z","updated_at":"2026-03-29T11:05:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heurema/herald","commit_stats":null,"previous_names":["real-ai-engineering/claude-news","heurema/herald"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/heurema/herald","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fherald","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fherald/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fherald/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fherald/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heurema","download_url":"https://codeload.github.com/heurema/herald/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fherald/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34916411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude","claude-code","claude-code-plugin","news-digest","rss"],"created_at":"2026-06-29T07:02:05.870Z","updated_at":"2026-06-29T07:02:07.582Z","avatar_url":"https://github.com/heurema.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n    __                    __    __\n   / /_  ___  _________ _/ /___/ /\n  / __ \\/ _ \\/ ___/ __ `/ / __  /\n / / / /  __/ /  / /_/ / / /_/ /\n/_/ /_/\\___/_/   \\__,_/_/\\__,_/\n```\n\n**Local-first news intelligence for AI agents.**\n\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-5b21b6?style=flat-square)]()\n[![Version](https://img.shields.io/github/v/tag/heurema/herald?label=version\u0026style=flat-square\u0026color=5b21b6)](https://github.com/heurema/herald)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\u003e Collect, cluster, and rank news from RSS and Hacker News — all locally, no API keys, no cloud.\n\n---\n\n## What it does\n\nHerald collects articles from RSS feeds and Hacker News, deduplicates by URL, clusters related articles into stories using title similarity, scores them by source weight and recency, and generates a ranked Markdown digest — all locally, no API keys, no cloud.\n\nThe pipeline: **collect → ingest → cluster → project**.\n\n```\nRSS/Atom feeds ─┐\n                 ├─→ articles ─→ stories (clustered) ─→ scored brief\nHN Algolia API ─┘\n```\n\n## Install\n\n\u003c!-- INSTALL:START — auto-synced from emporium/INSTALL_REFERENCE.md --\u003e\n```bash\nclaude plugin marketplace add heurema/emporium\nclaude plugin install herald@emporium\n```\n\u003c!-- INSTALL:END --\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eManual install from source\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/heurema/herald\ncd herald\npip install httpx fastfeedparser pyyaml\n```\n\nThen symlink or copy the plugin directory into Claude Code's plugin path and run `/news-init`.\n\n\u003c/details\u003e\n\n## Quick start\n\n```\n/news-init          # creates ~/.herald/ with config and database\n/news-add \u003curl\u003e     # add an RSS feed\n/news-run           # collect, ingest, cluster, generate brief\n/news-digest        # read the latest brief\n```\n\n## Commands\n\n| Command | What it does |\n|---------|-------------|\n| `/news-init` | Create data directory, config template, and database |\n| `/news-add \u003curl\u003e` | Add an RSS/Atom feed — auto-discovers feed URL |\n| `/news-sources` | View all sources grouped by category |\n| `/news-sources remove \u003cname\u003e` | Remove a source from config |\n| `/news-run` | Run the full pipeline manually |\n| `/news-digest` | Read the latest brief with 5-section analysis |\n| `/news-status` | Show article/story counts and last run time |\n| `/news-stop` | Show cleanup options |\n\n## Architecture\n\nHerald v2 uses a 4-stage pipeline with SQLite storage:\n\n1. **Collect** — fetches RSS/Atom feeds and HN front-page stories via public APIs. Optional Tavily adapter for web search.\n2. **Ingest** — UPSERT articles with URL canonicalization, deduplication, topic assignment, and cross-source mention tracking.\n3. **Cluster** — groups related articles into stories using `SequenceMatcher` title similarity with 4 merge guards (threshold, time gap, title length, version/number conflict). Canonical article re-election with hysteresis.\n4. **Project** — generates a Markdown brief with YAML frontmatter, stories grouped by type (release, research, tutorial, opinion, news), scored and ranked.\n\n### Data model\n\n```\nsources → articles → mentions (cross-source)\n                  → article_topics\n                  → story_articles → stories → story_topics\n```\n\n### Scoring\n\n- **Article score**: `source_weight + min(points/500, 3.0) + keyword_density * 0.2 + release_boost`\n- **Story score**: `max(article_scores) + log(source_count) * 0.3 + momentum`\n\n## Configuration\n\nConfig: `~/.herald/config.yaml`\n\n```yaml\nsources:\n  - id: hn\n    name: Hacker News\n    type: hn           # hn | rss | tavily\n    weight: 0.3\n    category: community\n  - id: simonw\n    name: Simon Willison\n    type: rss\n    url: https://simonwillison.net/atom/everything/\n    weight: 0.25\n    category: community\n\ntopics:\n  ai_agents:\n    keywords: [agent, agents, agentic, tool use, mcp]\n  ai_models:\n    keywords: [claude, gpt, gemini, llama, llm]\n\nclustering:\n  threshold: 0.65        # title similarity threshold\n  max_time_gap_days: 7   # max days between clustered articles\n\nschedule:\n  interval_hours: 4\n```\n\n### Data paths\n\n```\n~/.herald/\n├── config.yaml\n├── herald.db           # SQLite database\n└── briefs/\n    └── {run_id}.md     # generated briefs\n```\n\n## Requirements\n\n- Python 3.12+\n- `httpx`, `fastfeedparser`, `pyyaml`\n- macOS or Linux\n- Claude Code\n\n## Privacy\n\nHerald fetches only public RSS feeds and the HN Algolia API. All data stays on your machine under `~/.herald/`. No telemetry, no cloud sync. Optional Tavily adapter requires a free API key but is not needed for core functionality.\n\n## Feedback\n\nFound a bug? All heurema plugins ship with [Reporter](https://github.com/heurema/reporter) - file issues without leaving Claude Code:\n\n```bash\nclaude plugin install reporter@emporium\n/report bug\n```\n\n## See also\n\n- [Herald v2: Local-First News Intelligence for AI Agents](https://ctxt.dev/posts/en/herald-v2-local-news-intelligence) - blog post with architecture deep-dive\n- [emporium](https://github.com/heurema/emporium) - plugin marketplace\n- [signum](https://github.com/heurema/signum) - contract-first AI dev pipeline\n- [reporter](https://github.com/heurema/reporter) - issue filing from Claude Code\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheurema%2Fherald","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheurema%2Fherald","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheurema%2Fherald/lists"}