hn-axi

hn-axi

A Hacker News CLI built for agents. It wraps the Algolia HN API and follows the AXI ergonomic standard, so agents spend tokens on decisions, not on parsing.

Install it with uv, or run it one-off without installing:

uv tool install git+https://github.com/matthewdicataldo/hn-axi

uvx --from git+https://github.com/matthewdicataldo/hn-axi hn-axi

$ hn-axi search rust async --week --min-points 50 | head -5
count: 5 of 12 total
stories[5]{id,points,comments,title,url}:
  48952067,58,38,Topcoat: The full full-stack framework for Rust,https://github.com/tokio-rs/topcoat
  ...

Why not just curl the API?

Raw JSON is the wrong shape for an agent reading it through a shell tool. hn-axi exists to make every token count:

• TOON output — tabular rows with a single header instead of JSON's repeated keys, roughly 40% fewer tokens for the same data. On a TTY it switches to human-readable tables automatically (--format / HN_AXI_FORMAT to override).
• Minimal defaults, escape hatches everywhere — five fields per story, comments truncated at 300 chars, bodies at 500; --full, --comments N, and --fields when the agent actually needs more. No 50KB comment-tree dumps for a sentiment question.
• Pre-computed answers — recursive comment counts, result totals, page counts. The agent never burns a round trip computing what the tool already knows.
• Ready-to-run next steps — every output ends with a help[N]: block of literal follow-up commands (view this ID, widen this window, next page), so agents follow rails instead of guessing flags.
• Structured, loud errors — unknown flags, conflicting filters, and bad IDs fail immediately with a recovery hint (pass a comment ID and the error hands you the parent story ID). No tracebacks, no silent coercion.

What agents use it for

Tech due diligence. HN is where engineers say what they actually think. "What does HN make of Topcoat?" turns into a search, two thread reads, and an author check — a grounded answer with real quotes in a handful of calls.

Launch and ecosystem tracking. --show for what's shipping, --ask for what people are struggling with, --min-points to keep only what the community validated.

Jobs. hn-axi search --jobs filters YC job posts (search python --jobs --month for a stack-specific sweep), and the monthly "Who is hiring?" threads are one view <id> away.

Deep research. HN is a strong primary source for technical sentiment, but it's one source. In a research session the same agent can cross-reference hn-axi findings against its other tools — web search for docs and benchmarks, arXiv for papers — and parallel subagents can split the work:

Research how the HN community has reacted to AI coding tools over the past month.
Use one agent to search different queries (AI coding, Copilot, Cursor, Claude),
another to read comment threads for technical sentiment, and a third to check
author histories to weight credibility. Synthesize into a short report.

Simple asks work with no setup at all — point your coding agent (claude code, codex, etc.) at it:

Search HN for recent posts about Rust async and summarize the top 3.

What are people saying about the new Anthropic model release on HN? Pull the top story and its comments.

Teaching your agent about hn-axi (optional)

HN is a lookup tool, not something every session needs, so hn-axi does not inject itself into agent context. If you want your agent to know the tool exists and how to drive it well, install the agent skill:

npx skills add matthewdicataldo/hn-axi

The skills installer prompts you for which agents to target and works with Claude Code, Codex, Cursor, and most other harnesses. No Node? hn-axi skill install does the same thing (delegating to npx when available, otherwise writing SKILL.md to the standard skill directories directly), and hn-axi skill show prints the skill for any agent to read on demand.

Note on AXI guideline 7 (ambient context): the guideline says to install opt-in session integrations first and offer an on-demand skill second. hn-axi intentionally skips the session-hook half. That fits tools with high session relevance — task managers, issue trackers — where the agent almost always benefits from seeing current state up front. HN is a lookup tool: most sessions have nothing to do with it, so injecting a top-stories snapshot on every boot would be a recurring token cost with a near-zero hit rate. The skill is the whole story here, and it's opt-in.