> ## Documentation Index
> Fetch the complete documentation index at: https://www.opendirectory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# hackernews-intel

> Monitor Hacker News for keywords. Get a Slack alert every time a new post matches your topics, without duplicates. Run it manually, on a cron schedule, or vi...

<Info>
  **Category:** GTM Intelligence · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes)
</Info>

<img width="1280" height="640" alt="hackernews-intel" src="https://github.com/user-attachments/assets/8d75cba9-7c2b-4693-8365-00779ed2b3d3" />

Monitor Hacker News for keywords. Get a Slack alert every time a new post matches your topics, without duplicates. Run it manually, on a cron schedule, or via GitHub Actions.

## Install

<Tabs>
  <Tab title="npx CLI (Recommended)">
    ```bash theme={null}
    npx "@opendirectory.dev/skills" install hackernews-intel --target claude
    ```
  </Tab>

  <Tab title="skills.sh">
    ```bash theme={null}
    npx skills add Varnan-Tech/opendirectory --skill hackernews-intel
    ```
  </Tab>

  <Tab title="Claude Code Native">
    ```bash theme={null}
    /plugin marketplace add Varnan-Tech/opendirectory
    /plugin install opendirectory-gtm-skills@opendirectory-marketplace
    ```
  </Tab>

  <Tab title="Claude Desktop">
    <video controls className="w-full aspect-video rounded-xl mb-4" src="https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c" />

    1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/hackernews-intel` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP.
    2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`.
  </Tab>

  <Tab title="Manus AI">
    <video controls className="w-full aspect-video rounded-xl mb-4" src="https://github.com/user-attachments/assets/17cbee2a-9e17-4bd4-ac46-68e0e92ffab4" />

    [**Install hackernews-intel in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fhackernews-intel\&utm_source=opendirectory)
  </Tab>
</Tabs>

## What It Does

* Fetches new posts from HN using the free Algolia search API (no API key needed)
* Checks each match against a local SQLite cache and never alerts on the same post twice
* Sends a Slack notification with title, URL, points, and comment count
* Supports dry-run mode to preview matches without sending alerts
* Configurable lookback window, minimum points threshold, and comment inclusion

## Requirements

| Requirement | Purpose | Where to Get It |
| - | - | - |
| HN\_KEYWORDS | Keywords to monitor | Set in .env, comma-separated list |
| SLACK\_WEBHOOK | Slack alerts | [https://api.slack.com/apps](https://api.slack.com/apps), Incoming Webhooks |
| Node.js 20+ | Running the script | [https://nodejs.org](https://nodejs.org) |

No API key needed for Hacker News. The HN Algolia API is free and public.

## Setup

### 1. Set up dependencies

```bash theme={null}
cd hackernews-intel
npm install
```

### 2. Configure environment variables

```bash theme={null}
cp .env.example .env
```

Edit `.env`:

```bash theme={null}
HN_KEYWORDS=claude code,LLM agents,deno runtime
SLACK_WEBHOOK=https://hooks.slack.com/services/your/webhook/url
HN_MIN_POINTS=0
```

### 3. Create a Slack webhook

1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and create or select your app
2. Enable "Incoming Webhooks" in the app settings
3. Add a webhook to your workspace and select the target channel
4. Copy the webhook URL (starts with `https://hooks.slack.com/services/`)
5. Set it as `SLACK_WEBHOOK` in `.env`

## How to Use

Preview the last 7 days without sending alerts:

```bash theme={null}
npm run dry-run:week
# or
node scripts/monitor-hn.js --dry-run --days=7
```

Live run:

```bash theme={null}
npm run monitor
# or
node scripts/monitor-hn.js
```

Schedule via cron (every 4 hours):

```bash theme={null}
crontab -e
# Add:
0 */4 * * * cd /path/to/hackernews-intel && node scripts/monitor-hn.js >> /tmp/hn-intel.log 2>&1
```

Schedule via GitHub Actions:

```yaml theme={null}
name: HN Intel Monitor
on:
  schedule:
    - cron: '0 */4 * * *'
  workflow_dispatch:
jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: node scripts/monitor-hn.js
        env:
          HN_KEYWORDS: ${{ secrets.HN_KEYWORDS }}
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
```

Add `HN_KEYWORDS` and `SLACK_WEBHOOK` as repository secrets.

## Slack Alert Format

Each alert looks like:

```
Story Title Here
47 points  23 comments  authorname
Keyword: claude code  |  HN discussion
```

## Options

| Variable | Default | Purpose |
| - | - | - |
| `HN_KEYWORDS` | required | Comma-separated keywords |
| `SLACK_WEBHOOK` | required | Slack Incoming Webhook URL |
| `HN_MIN_POINTS` | `0` | Minimum points to alert |
| `HN_INCLUDE_COMMENTS` | `false` | Also monitor HN comments |
| `HN_DB_PATH` | `./hn-intel.db` | SQLite cache file path |

## CLI Flags

| Flag | Purpose |
| - | - |
| `--dry-run` | Preview matches without sending Slack alerts |
| `--days=N` | Lookback window for the first run (default: 1) |
| `--reset` | Clear the cache and start fresh |

## GitHub Actions Note

GitHub Actions does not persist files between workflow runs. The SQLite cache resets on each run, and the script re-fetches the last 1 day of posts every time. Posts from the previous run will be alerted again.

To fix this, either:

* Store `hn-intel.db` in an S3 bucket and download/upload it around the script run
* Use a self-hosted runner with persistent storage
* Use a cron job on your own machine instead

## Project Structure

```
hackernews-intel/
├── SKILL.md
├── README.md
├── .env.example
├── package.json
├── evals/
│   └── evals.json
└── scripts/
    └── monitor-hn.js
```

## License

MIT


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.