hn

A tiny Hacker News research CLI built for AI agents (and humans who like JSON).

• Stdlib only. No pip install, no deps. Python 3.9+.
• Two commands: search and thread.
• Compact JSON by default, --pretty for humans.
• Backed by the Algolia HN Search API — no key required.

Install

Zero-install (recommended for agents)

The script has a PEP 723 header, so uv handles everything:

git clone <this-repo> && cd hn-search
uv run hn.py search "rust async" --limit 5

No venv, no install — uv picks an interpreter and runs.

Persistent install (hn on PATH)

# with uv
uv tool install .

# or with pipx
pipx install .

hn search --tag front_page --limit 10

One-shot

uvx --from . hn search "..." --limit 5

As a Claude Code skill (skills.sh)

Install the bundled SKILL.md so Claude Code auto-discovers hn whenever a task involves HN research, trend-spotting, idea validation, or thread analysis:

npx skills add muneebhashone/hn

Note: this repo is currently private — you'll need read access (or to fork it public) for skills add to pull it.

Quick examples

# What's trending now
hn search --tag front_page --limit 10

# Has anyone shipped X recently?
hn search "claude code plugin" --since 30d --min-points 5

# Pain points in Ask HN
hn search --tag ask_hn --since 14d --min-comments 30

# Deep-dive a thread (top 3 branches, indented)
hn thread 48242959 --top 3 --pretty

# Works with URLs too
hn thread "https://news.ycombinator.com/item?id=48242959" --depth 2

# Mine a user's recent activity
hn search --tag author_dang --since 30d --limit 20

Tests

# Fast suite (112 tests, fully mocked, no network)
uv run --group dev pytest

# Include the live-API smoke tests (3 extra, hits Algolia)
HN_LIVE=1 uv run --group dev pytest
# On Windows PowerShell:
$env:HN_LIVE="1"; uv run --group dev pytest

Tests cover: duration / date parsing, HTML cleanup, URL & ID resolution, Algolia URL building (sort selection, tag joining, numeric filters, limit clamping), field trimming, comment-tree pruning (depth, min-score with strict mode, BFS comment cap, top-N branches), CLI argv → stdout / stderr / exit-code contract, error paths (HTTP error, network error, malformed JSON), and unicode handling.

For agents (Claude Code et al.)

Easiest path: npx skills add muneebhashone/hn (see skills.sh install above). Or drop SKILL.md into your skills directory manually / let your plugin loader find it.

See SKILL.md for the full agent-facing reference: flag tables, examples, and gotchas.

License

MIT.