Skip to content

README.md

Latest commit

 

History

History
287 lines (205 loc) · 9.27 KB

README.md

File metadata and controls

287 lines (205 loc) · 9.27 KB
Raw

hn

A terminal client for Hacker News.

Go version CI Release Downloads License

demo

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:

Source Value
HN_INSTALL_DIR used as-is
XDG_BIN_HOME used as-is
XDG_DATA_HOME $XDG_DATA_HOME/../bin
(default) $HOME/.local/bin

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
Skill What it does
hn-digest Scan the front page — today's themes, hot discussions, industry mix

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.

The digest is also published daily at hndigest.heartleo.dev.

DeepSeek Harness Plugin

For DeepSeek Harness there is hacker-news, a plain-ESM plugin that reads the public Hacker News APIs directly. It needs neither an HN API key nor a local terminal client.

Install from npm

The published package is dsh-hacker-news. It is also listed in the awesome-dsh-plugin community registry. DSH profiles are pnpm workspace roots, so keep the -w flag:

dsh plugin --profile <name> add -w dsh-hacker-news

If your npm mirror has not indexed the latest release, run the installation against the public registry:

$env:npm_config_registry = 'https://registry.npmjs.org/'
dsh plugin --profile <name> add -w dsh-hacker-news

Start or restart the same profile, then verify that the composed configuration includes dsh-hacker-news:

dsh --profile <name>
dsh --profile <name> --dump-config

Install from source

This form follows the repository's main branch and is intended for development or trying unreleased changes:

dsh plugin --profile <name> add -w github:heartleo/hn-cli#path:/plugins/hacker-news

After installation, ask naturally, for example: what's popular on HN?, search HN for sqlite, or read HN item 49322107 and summarize the discussion.

Tool What it does
hn_stories Ranked feeds — top / new / best / ask / show / job
hn_item An item plus its reply tree in reading order
hn_search Algolia search, by relevance or date
hn_user Karma, account age, bio, submission count

See the plugin README for configuration.

Quick Start

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

Commands

Browse

browse demo

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

comments demo

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

Key Action
Enter Open comment thread
o Open in browser
t Translate selected title
T Translate all visible titles
← / → Switch tab
r Refresh
? Toggle help
q / Ctrl+C Quit

Comment Thread

Key Action
j / ↓ Next comment
k / ↑ Previous comment
gg Back to top
r Jump to root comment
Enter Expand / collapse replies
Space Fold / unfold selected comment
C / E Fold / unfold all
t Translate selected comment
R Soft refresh
o Open story in browser
Esc Back to list
? Toggle help
Q / Ctrl+C Quit

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

Variable Default Description
HN_TRANSLATE_API_URL https://api.openai.com/v1 API base URL
HN_TRANSLATE_API_KEY — API key
HN_TRANSLATE_MODEL gpt-4o-mini Model name
HN_TRANSLATE_LANG Chinese Target language

Example .env:

HN_TRANSLATE_API_KEY=sk-...
HN_TRANSLATE_LANG=Chinese

Theme

Variable Description
HN_THEME Override theme without editing config

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:

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!