Skip to content

project.intent.md

Latest commit

 

History

History
57 lines (52 loc) · 4.89 KB

project.intent.md

File metadata and controls

57 lines (52 loc) · 4.89 KB

Herald — Project Intent

Goal

Herald is a local-first Claude Code plugin that provides news intelligence for AI agents: it collects articles from RSS feeds and Hacker News, deduplicates by URL, clusters related articles into stories via title similarity, scores them by source weight and recency, and generates a ranked Markdown brief — entirely on-device, no API keys required.

Core Capabilities

  • Bootstrap configuration, scheduler installation, and first fetch via /news-init [topic]
  • Add individual RSS/Atom feed URLs or curated topic packs via /news-add
  • List configured sources with tier weight and last-fetch status, or remove a source via /news-sources [remove <name>]
  • Read today's ranked digest (on-demand fetch if not yet available) via /news-digest
  • Trigger immediate fetch-and-analyze cycle outside normal schedule via /news-run
  • Show article/story counts and last pipeline run time via /news-status
  • Uninstall the scheduler while preserving config and historical data via /news-stop
  • Automatic session-start reminder via SessionStart hook when a fresh digest is available
  • Auto-activating news-digest skill that reads the digest inline when conversation contains trigger phrases
  • 4-stage local pipeline: Collect (RSS + HN Algolia + optional Tavily) → Ingest (URL canonicalization + dedup) → Cluster (SequenceMatcher title similarity) → Project (scored Markdown brief)
  • SQLite + FTS5 storage backend with WAL mode; no external database required
  • URL deduplication via canonicalization in Ingest stage + title similarity clustering (SequenceMatcher, default threshold 0.65, configurable)
  • Curated built-in topic packs: ai-engineering, rust, devops, golang, typescript, security, python, data
  • Two-layer config overlay: immutable preset (bundled YAML) + user override (~/.herald/config.yaml)
  • Cross-platform scheduler: launchd (macOS), systemd user timer (Linux), cron fallback
  • Optional Tavily web-search adapter for supplemental results (requires TAVILY_API_KEY)

Non-Goals

  • Real-time or sub-hourly news alerting — the pipeline is batch-based (daily by default); not designed for real-time push
  • Scheduler setup on systems without write access to ~/Library/LaunchAgents (macOS) or ~/.config/systemd/user/ (Linux) is not supported
  • Title-similarity deduplication for very short titles (under 5 words) is explicitly out of scope for reliable dedup

Success Criteria

  • Test suite passes under pytest with pythonpath = ["src"] and testpaths = ["tests"]
  • v2 database module creates all required tables (sources, articles, stories, story_articles, mentions, pipeline_runs) plus FTS5 virtual tables
  • Database has foreign keys enabled and runs in WAL journal mode
  • Plugin installs successfully via claude plugin install herald@emporium
  • /news-digest --demo returns a formatted digest (documented acceptance check in FAQ)
  • Scheduler is installed and fires at 07:00 daily (or configured interval); launchctl list | grep herald confirms loading on macOS
  • Brief output is stored as ~/.herald/briefs/{run_id}.md with YAML frontmatter

Personas

  • AI-Assisted Developer: A software engineer using Claude Code daily who wants a curated news brief injected into their session without leaving the terminal. Primary consumer of /news-digest and the auto-activating skill.
  • Plugin Installer / First-Time User: Someone running /news-init to bootstrap Herald for the first time, selecting a topic preset and verifying the scheduler is active. Relies on FAQ and troubleshooting docs.
  • Power User / Feed Curator: A user who actively manages sources with /news-add, /news-sources, and custom config.yaml overrides — adjusting tier weights, topic keywords, and clustering thresholds.
  • CI / Scheduled System: The launchd/systemd/cron scheduler that invokes run.sh daily. Automated, non-interactive. Reads no output; relies on lockfile discipline and log rotation.