HN TUI

A fast, keyboard-first Hacker News browser for the terminal. Read comments, search stories, and preview articles without leaving the command line.

Why this exists

If you spend time in the terminal, you already know the problem. Every time you want to check Hacker News, you reach for a browser. A tab opens. You get distracted. Twenty minutes later you are watching a video about someone restoring a rusty vise.

HN TUI keeps you in the flow. Stories load fast, comments render as a tree, and search covers the Hacker News archive. You can preview an article in the terminal or open the original in your browser when you actually need it.

Features

• Top, new, and best Hacker News feeds
• Arrow-key, vim-key, and space-bar navigation
• Threaded comment trees
• Persistent read tracking
• Full-database search through the Algolia HN API
• Optional terminal article previews with trafilatura
• One-key handoff to the original article in your browser
• Windows, Linux, and macOS support

Installation

Requirements: Python 3.9 or later and a terminal with curses support.

git clone https://github.com/Shreeniwas1/hackernews_TUI.git
cd hackernews_TUI
python -m venv .venv

Activate the virtual environment:

# Linux or macOS
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

The core client uses only Python's standard library. Install the optional article extractor for better previews:

python -m pip install trafilatura

Windows also needs the curses compatibility package:

python -m pip install windows-curses

Run the client:

python hn_tui.py

Controls

Key	Action
Arrow keys or j / k	Navigate stories and scroll comments
Enter or o	Open a story and load comments
/	Search Hacker News
p	Preview article text
f	Focus the comment pane
Tab or 1 / 2 / 3	Switch between top, new, and best
r	Refresh the current feed
q or Esc	Go back or quit

How it works

Stories come from the official Hacker News Firebase API. Search queries use the Algolia HN API and return up to 50 results. Threaded requests fetch stories and comments concurrently, and the rendered comment tree is cached to keep scrolling responsive.

Article preview uses trafilatura when installed and falls back to built-in HTML extraction. Read state is stored locally at ~/.cache/hn_tui_seen.json.

The application is one Python file with no database, web server, account, or configuration file.

License

MIT. See LICENSE.