hn

A terminal client for Hacker News.

Features

• 📰 Story browser — Top, New, Best, Ask HN, Show HN with tab switching
• 💬 Comment threads — navigate with j/k, fold/unfold, lazy-load reply trees
• 🌐 Translation — translate a title with t, all visible titles with T, or a selected comment
• 🔄 Soft refresh — refresh stories or comments without restarting
• 🎨 Themes — hn, mocha, dracula, tokyo, nord, gruvbox
• ⚡ Progressive loading — visible range loads first, more fetched as you scroll

Install

Homebrew (macOS / Linux):

$ brew install heartleo/tap/hn

winget (Windows):

$ winget install heartleo.hn

curl (macOS / Linux):

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh | sh

No sudo needed — the binary is installed under your home directory. The install
directory is picked from the first of these that is set:

To install somewhere else:

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh | HN_INSTALL_DIR=~/bin sh

The script warns if the install directory is not on your $PATH, and prints the
export PATH=... line to add to your shell profile.

The script never calls sudo. To install system-wide, run it as root yourself:

$ curl -fsSL https://raw.githubusercontent.com/heartleo/hn-cli/main/install.sh -o install.sh
$ sudo env HN_INSTALL_DIR=/usr/local/bin sh install.sh

Prebuilt binaries — download from GitHub Releases

Go install (requires Go 1.25+):

$ go install github.com/heartleo/hn-cli/cmd/hn@latest

Build from source:

$ git clone https://github.com/heartleo/hn-cli
$ cd hn
$ go build -o hn ./cmd/hn

Claude Code Plugin

This repo also ships hn, a Claude Code plugin that brings Hacker News to Claude.

/plugin marketplace add heartleo/hn-cli
/plugin install hn@hn-cli

Then just ask: what's on HN today. Ask in any language and the digest comes back in that language. See the plugin README for details.

Website

The same digest is published as a static site at hndigest.heartleo.dev — no Claude Code required, in English and Chinese.

A GitHub Action regenerates it hourly, skipping the model call when the front page hasn't changed. The backend defaults to GitHub Models, which is free and authenticates with the workflow's built-in token — there is no secret to configure. Point it at any OpenAI-compatible endpoint to use another provider:

Generate locally:

$ GITHUB_TOKEN=<token> go run ./cmd/hn-digest --out docs
$ go run ./cmd/hn-digest --out docs --force   # ignore the unchanged check

Quick Start

$ hn        # top stories
$ hn new    # new stories
$ hn best   # best stories

Commands

Browse

Opens the interactive TUI. Defaults to Top stories; switch tabs with ←/→.

$ hn        # top stories (default)
$ hn top
$ hn new
$ hn best
$ hn ask
$ hn show

Comments

Press Enter on any story to open its comment thread.

• navigate with ↑/↓ or k/j
• press Enter to expand or collapse a reply tree
• press Space to fold or unfold the selected comment
• press C / E to fold or unfold all
• press r to jump to the root comment
• press R to soft refresh
• press Esc to go back

Translation

Translates via any OpenAI-compatible chat completions API. See Configuration to set up an API key.

t   translate selected story title (toggle cached translation)
T   translate all visible titles in one batch request
t   translate selected comment (in comment view)

theme

$ hn theme          # show current
$ hn theme nord     # set globally

Available: hn · mocha · dracula · tokyo · nord · gruvbox

Keys

Story List

Comment Thread

Configuration

hn reads ~/.config/hn/config.json. A .env file in the working directory is also loaded automatically; environment variables take precedence over the config file.

Translation

Example .env:

HN_TRANSLATE_API_KEY=sk-...
HN_TRANSLATE_LANG=Chinese

Theme

Example ~/.config/hn/config.json:

{
  "theme": "mocha",
  "translate": {
    "api_url": "https://api.openai.com/v1",
    "api_key": "sk-...",
    "model": "gpt-4o-mini",
    "language": "Chinese"
  }
}

Contributing

Issues, bug reports, feature suggestions, and general feedback are very welcome:

• 🐛 Report a bug
• 💡 Suggest a feature

[!NOTE]
This project is maintained in my spare time, and I currently do not have enough capacity to properly review external pull requests. See CONTRIBUTING.md for details. Thank you for your understanding!